Clearspace exposes a lot of its functionality as web services. This topic describes the technology on which those services are based and provides examples on how you can use the services.
You can get Clearspace WSDL description files by requesting the following URL from your Clearspace instance: http://<hostname>:<portnumber>/<context>/rpc/soap/.
Note: By default, web services are disabled in Clearspace. You can enable them in the admin console. In the console, go to System > Settings > Web Services, then click Enable for the style you want. Be sure that the User Access and Force SSL settings are what you want also.
Clearspace Web Services use Document-Literal style binding with wrapped parameter format. This style was chosen for a number of reasons: it is WS-I compliant and the message is easily validated. There is also a general push towards Document-Literal style web services.
For a general description about web services styles see: http://www.ibm.com/developerworks/webservices/library/ws-whichwsdl/
Clearspace Web Services uses the Username Token Profile V1.0 (pdf) specification. The Username Token Profile specification is part of the OASIS Web Services Security (WS-Security) specification.
A header containing the username and password must be passed into every request. Here's an example:
<wsdl:Envelope xmlns:soap="..." xmlns:wsse="..." > <wsdl:Header> <wsse:Security> <wsse:UsernameToken> <wsse:Username>admin</wsse:Username> <wsse:Password>password</wsse:Password> </wsse:UsernameToken> </wsse:Security> </wsdl:Header> </wsdl:Envelope>
The following tables list the main classes of the API you use to access Clearspace web services. You'll find references for these in the Clearspace web services Javadoc.
| Object | Description |
|---|---|
| WSCommunity | A container for threads and a hierarchy of other communities. |
| WSDocument | Encapsulates a document in the Clearspace system. |
| WSForumMessage | Encapsulates discussion message data. |
| WSForumThread | A container for a hierarchy of ForumMessages. |
| WSGroup | Organizes users into a group for easier permissions management. |
| WSJiveObject | Super-class of other web service objects. |
| WSUser | Provides information about and services for users of the system. |
| WSWatch | A way for a user to track updates to an object. |
| Service | Description |
|---|---|
| AddressBookService | Provides ability to interact with the private message addressbook. |
| AttachmentService | A web service for managing attachment settings. |
| CommunityService | Provides the ability to manipulate communities. |
| DocumentService | Provides methods to load and manipulate documents. |
| ForumService | Provides the ability to manipulate discussion messages. |
| GroupService | Provides the ability for managing groups and group membership. |
| PermissionService | Provides a web service for managing permissions on users and groups. |
| PrivateMessageService | Provides the ability to manipulate private messages. |
| SearchService | Provides the ability to search for content. |
| SystemPropertiesService | Provides a web service for managing system properties. |
| UserService | Provides a web service for managing users, avatars, and status levels. |
| WatchService | A service for manipulating a user's watches on objects. |
Jive Software provides a Java client API for SOAP-based web services. The entry point to the client API is the class com.jivesoftware.community.webservices.ServiceLocator. The ServiceLocator handles authentication and provides getters for all of the services.
The following examples show how to use the client APIs to connect to the Clearspace service and perform various tasks. Note that most connections use the HTTPS protocol. We recommend this approach because it's the most secure. The system can be configured to use plain HTTP connections.
ServiceLocator locator = new ServiceLocator("https://myclearspace.com", "admin", "password"); CommunityService communityService = locator.getCommunityService(); Community community = communityService.getCommunity(1);
ServiceLocator locator = new ServiceLocator("https://myclearspace.com", "admin", "password"); CommunityService communityService = locator.getCommunityService(); ForumService forumService = locator.getForumService(); UserService userService = locator.getUserService(); // We want this thread to appear in the community with ID 33 Community community = communityService.getCommunity(33); // Get the user we want to post the message as User user = userService.getUser("myUsername"); // Create the thread ForumThread thread = forumService.createThread("My Test Message", "My message body", community.getID(), user.getID());
// The message to reply to long messageID = 1221; // The user we're posting the message as long userID = 12123; ServiceLocator locator = new ServiceLocator("https://myclearspace.com", "admin", "password"); ForumService contentService = locator.getContentService(); // Create the reply ForumMessage reply = forumService.createReplyMessage("my subject", "my response", message, userID);
// The message we're going add an attachment to long messageID = 12123; // Create a FileDataSource for the attachment. Do this with a DataSource object // (part of the Java Activation Framework) javax.activation.DataSource myData = new javax.activation.FileDataSource("/home/me/myfile.doc"); ServiceLocator locator = new ServiceLocator("https://myclearspace.com", "admin", "password"); ForumService svc = locator.getForumService(); svc.addAttachmenToMessage("myfile", myData, messageID);
ServiceLocator locator = new ServiceLocator("https://myfor.com", "admin", "password"); UserService svc = locator.getUserService(); User user = svc.createUser("johnsmith", "password", "johns@foo.com");
ServiceLocator locator = new ServiceLocator("https://myclearspace.com", "admin", "password"); ForumService forumService = locator.GetForumService(); long myThreadID = 333L; ArrayList<ForumMessage> messages = new ArrayList<ForumMessage>(); long[] messageIDs = forumService.getMessageIDsByThreadID(myThreadID); for (long messageID : messageIDs) { ForumMessage current = messageService.getForumMessage(messageID); messages.add(current); }
ServiceLocator locator = new ServiceLocator("https://myclearspace.com", "admin", "password"); SearchService service = locator.getSearchService(); Query query = new Query(); query.setQueryString("database java"); // Anything later than Jan 1, 2006 query.setAfterDate(new GregorianCalendar(2006, 1, 1).getTime()); query.setSortField(Query.DATE); query.setSortOrder(Query.ASCENDING); // Only grab the first 100 entries long[] messageIDs = service.messageSearch(query, 1, 100);
long myCommunityID = 3333L; ServiceLocator locator = new ServiceLocator("https://myclearspace.com", "admin", "password"); GroupService groupService = locator.getGroupService(); PermissionService permissionService = locator.getPermissionService(); Group group = groupService.getGroup("myGroup"); permissionService.addCommunityPermissionToGroup(com.jivesoftware.clearspace.Permissions.READ_COMMUNITY, true, group.getID(), myCommunityID);
The client APIs have the following dependencies. These are included with Clearspace.
| Library File | Description |
|---|---|
| activation.jar | Sun Java Activation Framework |
| commons-codec.jar | Apache Commons Codec library |
| commons-httpclient.jar | Apache Commons HTTP Client library |
| commons-logging.jar | Apache Commons Logging, A generic logging interface |
| cxf.jar | CXF libraries |
| geronimo.jar | Apache Geronimo, a J2EE server |
| google-collect.jar | Google utility classes for working with collections. |
| javamail.jar | Sun Mail Framework, used for attachments |
| jaxb-api.jar | Sun JAXB API |
| jaxb-impl.jar | Sun JAXB Impl |
| jaxb-xjc | Sun JAXB XJC |
| jaxen.jar | Jaxen, a XPath engine |
| jdom.jar | JDom, a library for manipulating XML as simple Java objects |
| jive-license.jar | Jive licensing internal API |
| stax-utils.jar | Utils for stax |
| sun-jaxws-api.jar | Sun Jax web services API |
| sun-saaj-api.jar | Sun SOAP Attachments API |
| sun-saaj-impl.jar | The Sun implementation of SAAJ |
| wsdl4j.jar | An API for manipulating WSDLs |
| wss4j.jar | The Apache implementation of the WS-Security spec |
| wstx-asl.jar | Woodstox is a STAX implementation from Codehaus |
| xml-resolver.jar | Required by CXF |
| XmlSchema.jar | XML Schema support |
| xmlsec.jar | XML Security |