com.tarantella.tta.webservices
Interface ITarantellaUtility

public interface ITarantellaUtility

Defines supporting web services.

Method Summary

java.lang.String	adminSearchEnd(java.lang.String sessionCookie, java.lang.String searchId) Cleans-up resources in the server for a given search.
java.lang.String	adminSearchNext(java.lang.String sessionCookie, java.lang.String searchId, int noOfResults) Retrieves the next subset of search results.
java.lang.String	adminSearchStart(java.lang.String sessionCookie, java.lang.String rootName, java.lang.String[] desiredAttributes, java.lang.String searchSpec, java.lang.String depth, java.lang.String nameFilter, int noOfResults, java.lang.String searchType) Starts a search on either the password or token caches.
java.lang.String	passcacheMigrate(java.lang.String sessionCookie, java.lang.String regexp, java.lang.String replacement) FOR INTERNAL USE only.
ResponseObject[]	sendBatchRequest(java.lang.String sessionCookie, RequestObject[] requests) Sends a batch of requests.
java.lang.String	sendKeepAlive(java.lang.String sessionCookie) Sends a keep-alive packet over the network connection.

Method Detail

adminSearchEnd

java.lang.String adminSearchEnd(java.lang.String sessionCookie,
                                java.lang.String searchId)
                                throws java.rmi.RemoteException

Cleans-up resources in the server for a given search. See adminSearchStart(String,String,String[],String,String,String,int,String).

Parameters:

sessionCookie - Identifies the user session performing the operation.

searchId - Identifies the search to clean-up.

Returns:

An empty top-level object

Throws:

java.rmi.RemoteException - On receipt of a SOAP fault.

Since:

1.0

adminSearchNext

java.lang.String adminSearchNext(java.lang.String sessionCookie,
                                 java.lang.String searchId,
                                 int noOfResults)
                                 throws java.rmi.RemoteException

Retrieves the next subset of search results. See adminSearchStart(String,String,String[],String,String,String,int,String).

Parameters:

sessionCookie - Identifies the user session performing the operation.

searchId - Identifies the search to use.

noOfResults - The maximum number of results to return from the search. If noOfResults <= 0, all results are returned.

Returns:

See adminSearchStart(String,String,String[],String,String,String,int,String).

Throws:

java.rmi.RemoteException - On receipt of a SOAP fault.

Since:

1.0

adminSearchStart

java.lang.String adminSearchStart(java.lang.String sessionCookie,
                                  java.lang.String rootName,
                                  java.lang.String[] desiredAttributes,
                                  java.lang.String searchSpec,
                                  java.lang.String depth,
                                  java.lang.String nameFilter,
                                  int noOfResults,
                                  java.lang.String searchType)
                                  throws java.rmi.RemoteException

Starts a search on either the password or token caches.

The search returns a maximum number of results. If the search finds more results than noOfResults, the results are cached on the server and subsequent sets can be retrieved by calling adminSearchNext(String, String, int). If not all of the results are retrieved and the search is no longer needed, adminSearchEnd(String, String) should be called. For use by administrators only.

Parameters:

sessionCookie - Identifies the user session performing the operation.

rootName - The full name from which to start searching.

.../_service/sco/tta/passcache	Search the password cache
.../_service/sco/tta/tokencache	Search the automatic login token cache

desiredAttributes - The attributes wanted in the response.

searchSpec - RFC 2254 search specification to select matching objects.

depth - The depth of sub-tree to search:

IConstants.DEPTH_ONELEVEL	Restrict the search to one level under the rootName
IConstants.DEPTH_SUBTREE	Search the whole sub-tree under the rootName

nameFilter - Regular expression to filter on object names.

noOfResults - The number of results to return from this search. If noOfResults <= 0, all results are returned.

searchType - Reserved for future use. An empty string should be provided.

Returns:

The IConstantsXML.NAME_SEARCHID attribute identifies the search and is returned in the top-level object. If this attribute has a non-empty value, then the search found more results than allowed by noOfResults. Subsequent results can be obtained by calling adminSearchNext(String, String, int) until that API returns an empty IConstantsXML.NAME_SEARCHID value, indicating that there are no more results.

If the search is abandoned before the attribute name IConstantsXML.NAME_SEARCHID is empty, then the search should be ended by calling adminSearchEnd(String, String). Failure to do so will consume server resources.

The cache objects are returned as children of the top-level object and named IConstantsXML.NAME_DATASTOREITEM. Each child corresponds to a cache entry.

 Sample response:
 <?xml version="1.0" encoding="UTF-8"?>
 <tta:response xmlns:tta="http://xml.tarantella.com/2001/soapreply.xsd">
  <obj name="datastoreitem">
   <attr name="datastoreitemname">".../_ens/o=Tarantella System Objects/cn=Administrator"</attr>
   <attr name="filemodifiedtime">1194878178000</attr>
   <attr name="filename">77eRLi7vt5BfZW5z77eQbz1UYXJhbnRlbGxhIFN5c3RlbSBPYmplY3Rz77eQY249QWRtaW5pc3RyYXRvcg==</attr>
   <attr name="filesize">188</attr>
   <attr name="fileaccessedtime">1195222073000</attr>
   <attr name="objectclass">top</attr>
   <attr name="objectclass">file</attr>
   <attr name="filepath">/opt/tarantella/var/password/tier3cache/77eRLi7vt5BfZW5z77eQbz1UYXJhbnRlbGxhIFN5c3RlbSBPYmplY3Rz77eQY249QWRtaW5pc3RyYXRvcg==</attr>
   <attr name="filecreationtime">1194878178000</attr>
  </obj>
  <obj name="datastoreitem">
   <attr name="datastoreitemname">".../_user/barrie"</attr>
   <attr name="filemodifiedtime">1195052886000</attr>
   <attr name="filename">77eRLi7vt5BfdXNlcu+3kGJhcnJpZQ==</attr>
   <attr name="filesize">188</attr>
   <attr name="fileaccessedtime">1195052886000</attr>
   <attr name="objectclass">top</attr>
   <attr name="objectclass">file</attr>
   <attr name="filepath">/opt/tarantella/var/password/tier3cache/77eRLi7vt5BfdXNlcu+3kGJhcnJpZQ==</attr>
   <attr name="filecreationtime">1195052886000</attr>
  </obj>
  <attr name="searchId">server.uk.sun.com:1195222072758:4638226410762143120:DS-1195224229797</attr>
 </tta:response>
 

Throws:

java.rmi.RemoteException - On receipt of a SOAP fault.

Since:

1.0

passcacheMigrate

java.lang.String passcacheMigrate(java.lang.String sessionCookie,
                                  java.lang.String regexp,
                                  java.lang.String replacement)
                                  throws java.rmi.RemoteException

FOR INTERNAL USE only. Performs password cache migration.

Parameters:

sessionCookie - Identifies the user session performing the operation.

regexp - An attribute regular expression against which to match.

replacement - Expression with which to replace each match.

Returns:

An empty top-level object

Throws:

java.rmi.RemoteException - On receipt of a SOAP fault.

Since:

1.0

sendBatchRequest

ResponseObject[] sendBatchRequest(java.lang.String sessionCookie,
                                  RequestObject[] requests)
                                  throws java.rmi.RemoteException

Sends a batch of requests. Used to optimise network traffic.

The batch request combines several API calls in a single request. Each web service request is placed inside a RequestObject.

Parameters:

sessionCookie - Identifies the user session on which the requests operate.

requests - Array of requests.

Returns:

Array of responses to the requests.

Throws:

java.rmi.RemoteException - On receipt of a SOAP fault.

Since:

1.0

sendKeepAlive

java.lang.String sendKeepAlive(java.lang.String sessionCookie)
                               throws java.rmi.RemoteException

Sends a keep-alive packet over the network connection.

Parameters:

sessionCookie - Identifies the user session performing the operation.

Returns:

An empty top-level object

Throws:

java.rmi.RemoteException - On receipt of a SOAP fault.

Since:

1.0