1.7.1 Working with Java Objects

The Web services operations often pass and return data within model objects as defined within the Kablink® Teaming software. This is beneficial because it cuts down on the amount of code required to prepare, send, receive, and interpret data. For example, parsing XML strings requires more coding. For users who develop Web services client applications in Java, Kablink Teaming provides a client-side library that they can use directly for added convenience. Users who develop Web services client applications in a language other than Java must rely on their own tools for understanding and coding the Kablink Teaming Web interfaces that have been defined and exposed by the corresponding WSDL.

Regardless of the language and tools that are used to develop Web services applications, it is helpful to familiarize yourself with some of the Teaming source code in order to understand the model objects and methods that are used to pass parameters and receive returned data.

To obtain the Kablink Teaming Web Services Java client library, download the Kablink Teaming product distribution tar/zip file, and expand it in a directory. This product distribution tar/zip file contains teaming-2.*.*-wsclient.zip. This file contains:

The kablink-teaming-wsclient.jar file contains the Java source that defines model objects that are passed between the Web services client and the Teaming server as either input arguments to or return values from various Web service operations. These model classes are located in the org/kablink/teaming/client/ws/model Java package. A significant number of the model classes build upon the base class DefinableEntity. The TeamingServiceSoapBindingStub.java class is the main stub class that application programs need to interact with in order to invoke various Web service operations.

To access Java sample programs that use the Kablink Teaming Web Services Java client library, download the Teaming source code from the Open Community Source page and examine the source code and scripts located in the /ssf/samples/wsclient directory. For example, the TeamingServiceClientWithStub.java class in /ssf/samples/wsclient/src/org/kablink/teaming/samples/wsclient demonstrates how to use the supplied stub and model classes to invoke Teaming Web services operations with minimum coding effort.

The kablink-teaming-wsclient.jar is also found with in the source tree in the /ssf/ws-client directory. To implement a client-side application of your own, all of the necessary libraries must be defined as being in your class path. When the sample program is run in /ssf/samples/wsclient, the accompanying build.xml Ant build script performs this function for you. It can be viewed as a template.

The names of the Web services operations use categories to organize the operations so they are easier for you to locate and understand. In general, the categories describe an item within Teaming that is the focus of the operation, such as folder, entry, binder, or attachments.

1.7.2 Adding Folders and the Binder Configuration Identifier

When you add a fully configured folder (template_addBinder), you need to specify a binder configuration identifier, which identifies the template used to configure a folder of a particular type. For example, the blog-folder template specifies settings used to configure a new blog folder.

To review the blog-folder template:

At the time of this writing, Teaming does not provide a message that you can use to retrieve the binder configuration identifier for a particular type of folder. Use the following procedure to obtain the binder configuration identifier for the folder you want to create:

The following figure shows an example of the binder configuration information for a blog folder, as found in the HTML source for the Add new folder page:

Figure 1-1 The Binder Configuration Identifier in Source Code

1.7.3 Attaching Files

In Novell Teaming, attachments are files that are associated with an entry. An entry can have more than one attached file.

For Web services, an attachment is a file exchanged in conjunction with an operation being passed between the client and server. Teaming recognizes only the first file attachment to an operation being sent to the server and ignores all other attachments.

To attach more than one file to an entry in Teaming, you must use one of the upload operations multiple times. For example, to attach 17 files to an entry in Teaming, you must use folder_uploadFile 17 times. Your client source code establishes where in the file system it finds or places files used as attachments to messages.

The folder_uploadFile operation requires that you pass a data item name. This identifier maps to the value specified in the name attribute of the input HTML tag used to upload the file; this value is also used in a hidden HTML tag that communicates values between the HTML form and the Teaming database.

To upload a file into the standard form element used to contain attachments, specify ss_attachFile1 as the data item name. If you are uploading files into a custom form element, create an instance of that custom entry, use an operation to get the name of the hidden field, then use the name when attaching files to the entry you actually want to affect.

1.7.4 Fetching Attachments

When you use folder_getEntry to obtain information about an entry, you use a Boolean parameter to indicate if you want the entry’s attachments. If you specify that you do want the attachments, your client establishes where on its system it places the attached files.

1.7.5 Adding Calendar Entries

When you pass the ical_uploadCalendarEntriesWithXML operation to the server, the Web services framework uses an XML formatted string of iCal data passed as the second parameter to the operation (<doc><entry>iCal data</entry></doc>).

1.7.6 Binder Pages and search_getWorkspaceTreeAsXML

When you use search_getWorkspaceTreeAsXML to obtain information about the hierarchical workspace tree, Novell Teaming returns XML formatted information about nodes in the tree, within the levels of the hierarchy you specify. Each node in the tree is a binder, which is typically a place (a workspace or folder). Sometimes, the XML element returned for a node is called a page.

The following graphic shows the workspace tree, which is expanded to show five levels of the workspace hierarchy:

Figure 1-2 Workspace Hierarchy Levels as Seen in the UI

In the graphic, each of the workspaces and folders are nodes in the workspace tree. The Workspaces workspace is the only binder at level 1. Level 2 binders include Global workspaces, Personal workspaces, and Team workspaces. The only binder shown at level 3 is the Corporate web site binder. Level 4 binders include folders and the December 2008 redesign workspace. The Calendar binder is located at level 5. If a binder has a plus sign next to it (for example, both the Global workspaces and Personal workspaces binders are preceded by plus signs), it means that there are hierarchy levels of binders that are not displayed in the UI.

If you use search_getWorkspaceTreeAsXML to get one level of the tree starting at the Workspaces node, Teaming returns information about Global workspaces, Personal workspaces, and Team workspaces.

As mentioned, some nodes in the tree are pages:

Figure 1-3 Pages as They Appear in the UI

The /ssf/web/docroot/WEB-INF/classes/config/ssf.properties file contains a property called wsTree.maxBucketSize, which, by default, is set to 25. This means that the maximum number of sub-workspaces allowed is 25. If a folder or workspace has more subplaces, Teaming creates virtual buckets called pages. Each line in Figure 1-3 corresponds to a page. The Personal workspaces workspace has two pages.

When you use search_getWorkspaceTreeAsXML to retrieve information about nodes in the workspace tree, it can return more than one hierarchical level as you specify, unless it encounters a page. To expand the tree beyond a page, you must call search_getWorkspaceTreeAsXML again, pass the binder identifier of the page, and pass the number of levels beyond the page you want to retrieve.

Consider the following:

Figure 1-4 A Page Containing Sub-Workspaces

The wong//zeeman page contains workspaces. The workspaces listed (Wong, Charles (cwong), and Zeeman, Skip szeeman)) are one level beyond the page.

When you receive page information as a node in the workspace tree, you receive page and tuple attributes. For example, page=”2” and pageTuple=”charles_wong (cwong)//skip_zeeman (szeeman)”. To obtain information about the contents of this page, you need to specify the identifier of the page’s parent, the number of hierarchy levels you want expanded, and a concatenation of the page number and tuple values, as shown in this example:

search_getWorkspaceTreeAsXML 24 3 "2//charles_wong//skip_zeeman"

This code begins at binder number 24, accesses page number 2, and returns two hierarchical levels of data for all users between Charles Wong and Skip Zeeman.

Given the structure of the Teaming pages and how Web services returns tree data, it is easiest to retrieve page data in this way. However, if you choose, you can actually retrieve paged tree data regardless of page number. To do this, specify any page number (Teaming actually ignores it), and specify a tuple in the correct order in which it appears in the tree, even if the set of users crosses pages. Teaming returns hierarchical information for all users in between the tuple values. However, if the number of returned nodes exceeds the value specified in the wsTree.maxBucketSize property (by default, 25 users), Teaming pages the data.

Finally, if you want to see all tree information without any page specifications, specify -1 as the value of the hierarchy levels you want returned.