org.xspace.service
Class XSpaceService

java.lang.Object
  extended byorg.xspace.service.XSpaceService

public class XSpaceService
extends java.lang.Object

An XSpace is a hierarchically-keyed repository for values, accessible globally via XSpaceService.
A key is simply a String with a tree path syntax. For example, /a/b/c
A value can be a String or an XML document.

XSpaceService provides the methods you'll need to interact with an XSpace.

The most useful methods when you are starting to use this API are:

createXSpace - to create an XSpace
put - to put a key/value into an XSpace
get - to get the value of a key in an XSpace
delete - to remove a key from an XSpace

Other useful methods are:

putXML - to put a key/value where value is an XML document
listXSpaces - to get a list of available XSpace names
createSubscriptionForEvents - to listen for XSpace events (for e.g.,when a key is added or deleted)
createSubscriptionForAdminEvents - to listen for admin events (for e.g., when an XSpace is created or deleted)


Method Summary
 XSpaceSubscriber createSubscriptionForAdminEvents(javax.jms.MessageListener listener)
          Creates a subscription for an XSpace administration event.
 XSpaceSubscriber createSubscriptionForEvents(java.lang.String xspaceName, javax.jms.MessageListener listener)
          Creates a subscription for an XSpace event.
 XSpaceSubscriber createSubscriptionForEvents(java.lang.String xspaceName, java.lang.String key, javax.jms.MessageListener listener)
          Creates a subscription for an XSpace event for a specified key.
 int createXSpace(java.lang.String xspaceName)
          Creates an XSpace with the given name
 void delete(java.lang.String xspaceName, java.lang.String key)
          Deletes a key from an XSpace
 void deleteXSpace(java.lang.String xspaceName)
          Deletes an XSpace with the given name
 java.lang.String[] findChildrenPaths(java.lang.String xspaceName, java.lang.String path, boolean fullPath)
          Returns all immediate children paths for a specified path.
 java.lang.String[] findDescendantPaths(java.lang.String xspaceName, java.lang.String path)
          Returns all descendant paths for a specified path.
 XSpaceItem get(java.lang.String xspaceName, java.lang.String key)
          Gets the value for a key in an XSpace
 java.lang.String[] getAllKeys(java.lang.String xspaceName)
          Gets all the keys in an XSpace.
static XSpaceService getInstance()
          Returns a handle to the non-authenticated XSpaceService.
static XSpaceService getInstance(XSpaceCredential credential)
          Returns a handle to the authenticated XSpaceService.
 java.lang.String[] getKeys(java.lang.String xspaceName, java.lang.String path)
          Gets all the keys starting at the given path in an XSpace
 java.lang.String[] listXSpaces()
          Lists the names of all XSpaces
 void put(java.lang.String xspaceName, java.lang.String key, java.lang.String value)
          Puts a value for a key in an XSpace
 void putXML(java.lang.String xspaceName, java.lang.String key, org.w3c.dom.Document document)
          Puts an XML document as a value for a key in an XSpace
 java.lang.String[] search(java.lang.String xspaceName, java.lang.String path, java.lang.String searchString)
          Searches an XSpace for values containing the search string.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getInstance

public static XSpaceService getInstance()
Returns a handle to the non-authenticated XSpaceService.

Returns:
the XSpace handle

getInstance

public static XSpaceService getInstance(XSpaceCredential credential)
Returns a handle to the authenticated XSpaceService.

Parameters:
credential - the user ID/password credential
Returns:
the XSpace handle

createXSpace

public int createXSpace(java.lang.String xspaceName)
                 throws java.rmi.RemoteException,
                        org.xspace.util.XSpaceException
Creates an XSpace with the given name

Parameters:
xspaceName - the XSpace name
Returns:
an identifier for the newly created XSpace
Throws:
java.rmi.RemoteException
org.xspace.util.XSpaceException

deleteXSpace

public void deleteXSpace(java.lang.String xspaceName)
                  throws java.rmi.RemoteException,
                         org.xspace.util.XSpaceException
Deletes an XSpace with the given name

Parameters:
xspaceName - the XSpace name
Throws:
java.rmi.RemoteException
org.xspace.util.XSpaceException

listXSpaces

public java.lang.String[] listXSpaces()
                               throws java.rmi.RemoteException,
                                      org.xspace.util.XSpaceException
Lists the names of all XSpaces

Returns:
an array of XSpace names
Throws:
java.rmi.RemoteException
org.xspace.util.XSpaceException

put

public void put(java.lang.String xspaceName,
                java.lang.String key,
                java.lang.String value)
         throws java.rmi.RemoteException,
                org.xspace.util.XSpaceException
Puts a value for a key in an XSpace

Parameters:
xspaceName - the name of the XSpace
key - the key (the format must adhere to XSpace path syntax: e.g. /a/b/c)
value - the string value
Throws:
java.rmi.RemoteException
org.xspace.util.XSpaceException

putXML

public void putXML(java.lang.String xspaceName,
                   java.lang.String key,
                   org.w3c.dom.Document document)
            throws java.rmi.RemoteException,
                   org.xspace.util.XSpaceException
Puts an XML document as a value for a key in an XSpace

Parameters:
xspaceName - the name of the XSpace
key - the key (the format must adhere to XSpace path syntax: e.g. /a/b/c)
document - the XML document
Throws:
java.rmi.RemoteException
org.xspace.util.XSpaceException

get

public XSpaceItem get(java.lang.String xspaceName,
                      java.lang.String key)
               throws java.rmi.RemoteException,
                      org.xspace.util.XSpaceException
Gets the value for a key in an XSpace

Parameters:
xspaceName - the name of the XSpace
key - the key (the format must adhere to XSpace path syntax: e.g. /a/b/c)
Returns:
value the value
Throws:
java.rmi.RemoteException
org.xspace.util.XSpaceException

delete

public void delete(java.lang.String xspaceName,
                   java.lang.String key)
            throws java.rmi.RemoteException,
                   org.xspace.util.XSpaceException
Deletes a key from an XSpace

Parameters:
xspaceName - the name of the XSpace
key - the key (the format must adhere to XSpace path syntax: e.g. /a/b/c)
Throws:
java.rmi.RemoteException
org.xspace.util.XSpaceException

getKeys

public java.lang.String[] getKeys(java.lang.String xspaceName,
                                  java.lang.String path)
                           throws java.rmi.RemoteException,
                                  org.xspace.util.XSpaceException
Gets all the keys starting at the given path in an XSpace

Parameters:
xspaceName - the name of the XSpace
path - the path (e.g. /, /a, /a/b/c)
Returns:
an array of keys
Throws:
java.rmi.RemoteException
org.xspace.util.XSpaceException

getAllKeys

public java.lang.String[] getAllKeys(java.lang.String xspaceName)
                              throws java.rmi.RemoteException,
                                     org.xspace.util.XSpaceException
Gets all the keys in an XSpace. Equivalent to calling getKeys with "/" as the path

Parameters:
xspaceName - the name of the XSpace
Returns:
an array of keys
Throws:
java.rmi.RemoteException
org.xspace.util.XSpaceException

findChildrenPaths

public java.lang.String[] findChildrenPaths(java.lang.String xspaceName,
                                            java.lang.String path,
                                            boolean fullPath)
                                     throws java.rmi.RemoteException,
                                            org.xspace.util.XSpaceException
Returns all immediate children paths for a specified path. For example, if the following keys exist: /a/b, /a/c, /a/d then this method would return b, c, d as the children of /a

Parameters:
xspaceName - the name of the XSpace
path - the starting path
fullPath - a flag indicating whether the returned paths should be full paths
Returns:
an array of paths (keys)
Throws:
java.rmi.RemoteException
org.xspace.util.XSpaceException

findDescendantPaths

public java.lang.String[] findDescendantPaths(java.lang.String xspaceName,
                                              java.lang.String path)
                                       throws java.rmi.RemoteException,
                                              org.xspace.util.XSpaceException
Returns all descendant paths for a specified path. For example, if the following keys exist: /a/b, /a/c, /a/c/d, /a/c/e then this method would return /a/b, /a/c, /a/c/d and /a/c/e as the descendants of /a

Parameters:
xspaceName - the name of the XSpace
path - the starting path
Returns:
an array of paths (keys)
Throws:
java.rmi.RemoteException
org.xspace.util.XSpaceException

search

public java.lang.String[] search(java.lang.String xspaceName,
                                 java.lang.String path,
                                 java.lang.String searchString)
                          throws java.rmi.RemoteException,
                                 org.xspace.util.XSpaceException
Searches an XSpace for values containing the search string. The search can begin from any node in the tree. For example to search an entire tree, simply pass in "/" (root) as the starting path. An array of keys containing the search results is returned. If no results are found, an empty array is returned.

Parameters:
xspaceName - the name of the XSpace
path - the starting path
searchString - the search string
Returns:
an array of paths (keys)
Throws:
java.rmi.RemoteException
org.xspace.util.XSpaceException

createSubscriptionForEvents

public XSpaceSubscriber createSubscriptionForEvents(java.lang.String xspaceName,
                                                    javax.jms.MessageListener listener)
                                             throws org.xspace.util.XSpaceException,
                                                    javax.jms.JMSException
Creates a subscription for an XSpace event. An XSpace event could be one of the following:
1. a new key/value has been added to the XSpace
2. the value has been updated for an existing key in the XSpace
3. a key has been deleted from the XSpace
The event will be delivered wrapped in a JMS message to the listener's onMessage method.

Parameters:
xspaceName - the name of the XSpace
listener - the listener (which implements javax.jms.MessageListener interface)
Returns:
a handle to the subsriber. To stop receiving events, invoke close() on this subscriber.
Throws:
org.xspace.util.XSpaceException
javax.jms.JMSException

createSubscriptionForEvents

public XSpaceSubscriber createSubscriptionForEvents(java.lang.String xspaceName,
                                                    java.lang.String key,
                                                    javax.jms.MessageListener listener)
                                             throws org.xspace.util.XSpaceException,
                                                    javax.jms.JMSException
Creates a subscription for an XSpace event for a specified key. An XSpace event could be one of the following:
1. the specified key with value has been added to the XSpace
2. the value has been updated for an existing specified key in the XSpace
3. the specified key has been deleted from the XSpace
The event will be delivered wrapped in a JMS message to the listener's onMessage method.

Parameters:
xspaceName - the name of the XSpace
key - the key
listener - the listener (which implements javax.jms.MessageListener interface)
Returns:
a handle to the subsriber. To stop receiving events, invoke close() on this subscriber.
Throws:
org.xspace.util.XSpaceException
javax.jms.JMSException

createSubscriptionForAdminEvents

public XSpaceSubscriber createSubscriptionForAdminEvents(javax.jms.MessageListener listener)
                                                  throws org.xspace.util.XSpaceException,
                                                         javax.jms.JMSException
Creates a subscription for an XSpace administration event. An XSpace administration event could be one of the following:
1. an XSpace has been created
2. an XSpace has been deleted
The event will be delivered wrapped in a JMS message to the listener's onMessage method.

Parameters:
listener - the listener (which implements javax.jms.MessageListener interface)
Returns:
a handle to the subsriber. To stop receiving events, invoke close() on this subscriber.
Throws:
org.xspace.util.XSpaceException
javax.jms.JMSException