Oracle Secure Global Desktop Web Services API Documentation
Release 4.7

E21396-02

com.tarantella.tta.webservices
Interface ITarantellaEmulatorSession


public interface ITarantellaEmulatorSession

Defines the web services for managing application sessions.

A Secure Global Desktop (SGD) application session is an instance of a running application.


Method Summary
 java.lang.String adminCount(java.lang.String sessionCookie, java.lang.String searchSpec)
          Counts the number of matching application sessions that a search would return.
 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 searchSpec, java.lang.String[] desiredAttributes, int noOfResults, java.lang.String searchType)
          Starts a search, returning a maximum number of results.
 java.lang.String endSession(java.lang.String sessionCookie, java.lang.String emulatorSessionId)
          Ends an application session.
 java.lang.String endSessions(java.lang.String sessionCookie, java.lang.String[] emulatorSessionIds)
          Ends one or more application sessions.
 java.lang.String lookupSessions(java.lang.String sessionCookie, java.lang.String[] emulatorSessionIds, java.lang.String[] desiredAttributes)
          Looks-up attributes for one or more application sessions.
 java.lang.String resumeSession(java.lang.String sessionCookie, java.lang.String emulatorSessionId)
          Resumes a suspended application session.
 java.lang.String resumeSessionInPlace(java.lang.String sessionCookie, java.lang.String emulatorSessionId, java.lang.String launcherId)
          Deprecated. This API behaves identically to resumeSession(String, String)
 java.lang.String search(java.lang.String sessionCookie, java.lang.String searchSpec, java.lang.String[] desiredAttributes)
          Searches for application sessions.
 java.lang.String startSession(java.lang.String sessionCookie, java.lang.String applicationName, Item[] launchOptions)
          Starts an application session by launching an application.
 java.lang.String startSessionInPlace(java.lang.String sessionCookie, java.lang.String applicationName, java.lang.String launcherId, Item[] launchOptions)
          Deprecated. This API behaves identically to startSession(String, String, Item[]).
 java.lang.String suspendSession(java.lang.String sessionCookie, java.lang.String emulatorSessionId)
          Suspends an application session.
 

Method Detail

adminCount

java.lang.String adminCount(java.lang.String sessionCookie,
                            java.lang.String searchSpec)
                            throws java.rmi.RemoteException
Counts the number of matching application sessions that a search would return. For use by Administrators only

Parameters:
sessionCookie - Identifies the user session performing the operation.
searchSpec - RFC 2254 search specification to select matching application sessions.
Returns:
The number of matching objects is returned as the attribute IAttributeNames.TOTAL in the top-level object.

 Sample response:
 <?xml version="1.0" encoding="UTF-8"?>
 <tta:response xmlns:tta="http://xml.tarantella.com/2001/soapreply.xsd">
  <attr name="total">1</attr>
 </tta:response>
 
Throws:
java.rmi.RemoteException - On receipt of a SOAP fault.
Since:
1.0

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[], 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[], int, String).

Parameters:
sessionCookie - Identifies the user session performing the operation.
searchId - Identifies the search to use.
noOfResults - The number of results to return from the search. If noOfResults <= 0 all results are returned.
Returns:
See adminSearchStart(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 searchSpec,
                                  java.lang.String[] desiredAttributes,
                                  int noOfResults,
                                  java.lang.String searchType)
                                  throws java.rmi.RemoteException
Starts a search, returning a maximum number of results. If the search returns 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.
searchSpec - RFC2254 search specification to select matching application sessions.
desiredAttributes - Array of attributes wanted in the response. IConstants.LOCAL_ATTRS is a shortcut to get those attributes that can be retrieved cheaply (see sample response).
noOfResults - The maximum 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 results for the application sessions are returned in the children of the top-level object. See search(String, String, String[]) for details.

 Sample response:
 <?xml version="1.0" encoding="UTF-8"?>
 <tta:response xmlns:tta="http://xml.tarantella.com/2001/soapreply.xsd">
  See search(String, String, String[]) for details
  <attr name="searchId">server.uk.sun.com:1194952979813:4596222405879589000:ES-1194967684089</attr>
 </tta:response>
Throws:
java.rmi.RemoteException - On receipt of a SOAP fault.
Since:
1.0

endSession

java.lang.String endSession(java.lang.String sessionCookie,
                            java.lang.String emulatorSessionId)
                            throws java.rmi.RemoteException
Ends an application session. Administrators can end sessions belonging to any user, other users can only end their own.
NOTE: this API cannot be guaranteed to stop the application cleanly and should be used with caution. Whenever possible, users should close their applications.

Parameters:
sessionCookie - Identifies the user session performing the operation.
emulatorSessionId - Identifies the application session.
Returns:
An empty top-level object
Throws:
java.rmi.RemoteException - On receipt of a SOAP fault.
Since:
1.0

endSessions

java.lang.String endSessions(java.lang.String sessionCookie,
                             java.lang.String[] emulatorSessionIds)
                             throws java.rmi.RemoteException
Ends one or more application sessions. Administrators can end sessions belonging to any user, other users can only end their own.
NOTE: this API cannot be guaranteed to stop the applications cleanly and should be used with caution. Whenever possible, users should close their applications.

Parameters:
sessionCookie - Identifies the user session performing the operation.
emulatorSessionIds - Identifies the application sessions.
Returns:
An empty top-level object
Throws:
java.rmi.RemoteException - On receipt of a SOAP fault.
Since:
1.0

lookupSessions

java.lang.String lookupSessions(java.lang.String sessionCookie,
                                java.lang.String[] emulatorSessionIds,
                                java.lang.String[] desiredAttributes)
                                throws java.rmi.RemoteException
Looks-up attributes for one or more application sessions. Administrators can look-up values on sessions belonging to any user, other users can only look-up their own.

Parameters:
sessionCookie - Identifies the user session performing the operation.
emulatorSessionIds - Array of application session IDs.
desiredAttributes - Array of attributes wanted in the response. IConstants.LOCAL_ATTRS is a shortcut to get those attributes that can be retrieved cheaply (see sample response).
Returns:
The attributes are returned in children of the top-level object named IConstantsXML.NAME_EMULATORSESSION, where each child corresponds to an SGD application session. Each application session object contains the desired attributes. See search(String, String, String[]) for details.
Throws:
java.rmi.RemoteException - On receipt of a SOAP fault.
Since:
1.0

resumeSession

java.lang.String resumeSession(java.lang.String sessionCookie,
                               java.lang.String emulatorSessionId)
                               throws java.rmi.RemoteException
Resumes a suspended application session.

Parameters:
sessionCookie - Identifies the user session performing the operation.
emulatorSessionId - Identifies the application session.
Returns:
See startSession(String, String, Item[])
Throws:
java.rmi.RemoteException - On receipt of a SOAP fault.
Since:
1.0

resumeSessionInPlace

@Deprecated
java.lang.String resumeSessionInPlace(java.lang.String sessionCookie,
                                                 java.lang.String emulatorSessionId,
                                                 java.lang.String launcherId)
                                      throws java.rmi.RemoteException
Deprecated. This API behaves identically to resumeSession(String, String)

Throws:
java.rmi.RemoteException

search

java.lang.String search(java.lang.String sessionCookie,
                        java.lang.String searchSpec,
                        java.lang.String[] desiredAttributes)
                        throws java.rmi.RemoteException
Searches for application sessions. Administrators can search for sessions belonging to any user, other users can only search for their own.

Parameters:
sessionCookie - Identifies the user session performing the operation.
searchSpec - RFC 2254 search specification for selecting matching application sessions.
desiredAttributes - Array of attributes wanted in the response. IConstants.LOCAL_ATTRS is a shortcut to get those attributes that can be retrieved cheaply (see sample response).
Returns:
The attributes are returned in children of the top-level object named IConstantsXML.NAME_EMULATORSESSION, where each child corresponds to an SGD application session. Each application session object contains the desired attributes. Interesting attributes:
ISchemaNames.ENSEQUIVNAME The session configuration of the owner of the application session.
ISchemaNames.SESSION_APPNAME The fully-qualified name of the application object.
ISchemaNames.SESSION_USER The name of the application server user.
ISchemaNames.SESSION_OWNER The owner of the application session.
ISchemaNames.SESSION_ID The application session ID.
ISchemaNames.SESSION_LAUNCHTIME The time at which the application session was launched.
ISchemaNames.SESSION_LAUNCHENS The fully-qualified name of the application server on which the application session was launched.
ISchemaNames.SESSION_LAUNCHHOST The DNS name of the application server.
ISchemaNames.SESSION_PEID The PID of the protocol engine running the application session.
ISchemaNames.SESSION_RESUMABLE The resumability of the application session.

 Sample response:
 <?xml version="1.0" encoding="UTF-8"?>
 <tta:response xmlns:tta="http://xml.tarantella.com/2001/soapreply.xsd">
  <obj name="emulatorsession">
   <attr name="scottaauthoritativesource">server.uk.sun.com</attr>
   <attr name="scottasessiontemplateowner">.../_ens/o=Tarantella System Objects/cn=Administrator</attr>
   <attr name="scottasessionappname">.../_ens/o=applications/cn=xclock (server)</attr>
   <attr name="scottasessionusername">root</attr>
   <attr name="scottabillingliveperiod">1</attr>
   <attr name="objectclass">top</attr>
   <attr name="objectclass">scottasession</attr>
   <attr name="objectclass">scottalaunchablesession</attr>
   <attr name="objectclass">scottaapplicationsession</attr>
   <attr name="scottasessionexternaldnsname">server.uk.sun.com</attr>
   <attr name="scottasessionowner">.../_ens/o=Tarantella System Objects/cn=Administrator</attr>
   <attr name="scottasessionappclass">scottaxapplication</attr>
   <attr name="scottasessionappclass">scottaapplication</attr>
   <attr name="scottasessionappclass">top</attr>
   <attr name="scottasessiondisplayusing">awtwindow</attr>
   <attr name="scottasessionid">server.uk.sun.com:1195116253260:-3013416157188449871:Li4uL19lbnMvbz1UYXJhbnRlbGxhIFN5c3RlbSBPYmplY3RzL2NuPUFkbWluaXN0cmF0b3I=</attr>
   <attr name="scottapename">xpeconfig</attr>
   <attr name="scottasessionpeerdnsname">server.uk.sun.com</attr>
   <attr name="scottasessiontoken">.../_token/"7EdFxBJU/s0rIKHtHx1Qcd4Y45g="</attr>
   <attr name="scottasessionwidth">200</attr>
   <attr name="scottasessionheight">200</attr>
   <attr name="scottasessionlaunchtime">1195116253262</attr>
   <attr name="scottasessionport">3144</attr>
   <attr name="scottasessionlaunchhostens">.../_ens/o=appservers/cn=Tarantella server server</attr>
   <attr name="scottasessionlaunchhostname">server.uk.sun.com</attr>
   <attr name="scottasessionpeid">8579</attr>
   <attr name="scottasessionresumable">never</attr>
   <attr name="scottasessionxauthcookie">710bf39fdc361236f4be01c529a9f70b</attr>
   <attr name="scottasessionresumablefor">0</attr>
   <attr name="scottasessionsecurity">std</attr>
  </obj>
  <obj name="emulatorsession">
   <attr name="scottaauthoritativesource">server.uk.sun.com</attr>
   <attr name="scottasessiontemplateowner">.../_ens/o=Tarantella System Objects/cn=Administrator</attr>
   <attr name="scottasessionappname">.../_ens/o=applications/cn=xclock (server)</attr>
   <attr name="scottasessionusername">root</attr>
   <attr name="scottabillingliveperiod">0</attr>
   <attr name="objectclass">top</attr>
   <attr name="objectclass">scottasession</attr>
   <attr name="objectclass">scottalaunchablesession</attr>
   <attr name="objectclass">scottaapplicationsession</attr>
   <attr name="scottasessionexternaldnsname">server.uk.sun.com</attr>
   <attr name="scottasessionowner">.../_ens/o=Tarantella System Objects/cn=Administrator</attr>
   <attr name="scottasessionappclass">scottaxapplication</attr>
   <attr name="scottasessionappclass">scottaapplication</attr>
   <attr name="scottasessionappclass">top</attr>
   <attr name="scottasessiondisplayusing">awtwindow</attr>
   <attr name="scottasessionid">server.uk.sun.com:1195117232294:1986707411109967997:Li4uL19lbnMvbz1UYXJhbnRlbGxhIFN5c3RlbSBPYmplY3RzL2NuPUFkbWluaXN0cmF0b3I=</attr>
   <attr name="scottapename">xpeconfig</attr>
   <attr name="scottasessionpeerdnsname">server.uk.sun.com</attr>
   <attr name="scottasessiontoken">.../_token/"7EdFxBJU/s0rIKHtHx1Qcd4Y45g="</attr>
   <attr name="scottasessionwidth">200</attr>
   <attr name="scottasessionheight">200</attr>
   <attr name="scottasessionlaunchtime">1195117232296</attr>
   <attr name="scottasessionport">3144</attr>
   <attr name="scottasessionlaunchhostens">.../_ens/o=appservers/cn=Tarantella server server</attr>
   <attr name="scottasessionlaunchhostname">server.uk.sun.com</attr>
   <attr name="scottasessionpeid">8579</attr>
   <attr name="scottasessionresumable">never</attr>
   <attr name="scottasessionxauthcookie">a9352598bfd608cfcaa84edfa61218d4</attr>
   <attr name="scottasessionresumablefor">0</attr>
   <attr name="scottasessionsecurity">std</attr>
  </obj>
  <obj name="emulatorsession">
   <attr name="scottaauthoritativesource">server.uk.sun.com</attr>
   <attr name="scottasessiontemplateowner">.../_ens/o=Tarantella System Objects/cn=Administrator</attr>
   <attr name="scottasessionappname">.../_ens/o=applications/cn=xclock (server)</attr>
   <attr name="scottasessionusername">root</attr>
   <attr name="scottabillingliveperiod">1</attr>
   <attr name="objectclass">top</attr>
   <attr name="objectclass">scottasession</attr>
   <attr name="objectclass">scottalaunchablesession</attr>
   <attr name="objectclass">scottaapplicationsession</attr>
   <attr name="scottasessionexternaldnsname">server.uk.sun.com</attr>
   <attr name="scottasessionowner">.../_ens/o=Tarantella System Objects/cn=Administrator</attr>
   <attr name="scottasessionappclass">scottaxapplication</attr>
   <attr name="scottasessionappclass">scottaapplication</attr>
   <attr name="scottasessionappclass">top</attr>
   <attr name="scottasessiondisplayusing">awtwindow</attr>
   <attr name="scottasessionid">server.uk.sun.com:1195117237078:3666769115915395504:Li4uL19lbnMvbz1UYXJhbnRlbGxhIFN5c3RlbSBPYmplY3RzL2NuPUFkbWluaXN0cmF0b3I=</attr>
   <attr name="scottapename">xpeconfig</attr>
   <attr name="scottasessionpeerdnsname">server.uk.sun.com</attr>
   <attr name="scottasessiontoken">.../_token/"7EdFxBJU/s0rIKHtHx1Qcd4Y45g="</attr>
   <attr name="scottasessionwidth">200</attr>
   <attr name="scottasessionheight">200</attr>
   <attr name="scottasessionlaunchtime">1195117237080</attr>
   <attr name="scottasessionport">3144</attr>
   <attr name="scottasessionlaunchhostens">.../_ens/o=appservers/cn=Tarantella server server</attr>
   <attr name="scottasessionlaunchhostname">server.uk.sun.com</attr>
   <attr name="scottasessionpeid">8579</attr>
   <attr name="scottasessionresumable">never</attr>
   <attr name="scottasessionxauthcookie">45631ab11279f7c70e7f712f5985da7f</attr>
   <attr name="scottasessionresumablefor">0</attr>
   <attr name="scottasessionsecurity">std</attr>
  </obj>
 </tta:response>
 
Throws:
java.rmi.RemoteException - On receipt of a SOAP fault.
Since:
1.0

startSession

java.lang.String startSession(java.lang.String sessionCookie,
                              java.lang.String applicationName,
                              Item[] launchOptions)
                              throws java.rmi.RemoteException
Starts an application session by launching an application.

Parameters:
sessionCookie - Identifies the user session performing the operation.
applicationName - The name of the application to launch.
launchOptions - Array of optional overrides for the launch, including:
IConstants.OPTION_FORCE_AUTHENTICATION If set to true, the SGD server will prompt for application server authentication even if the user has cached credentials.
IConstants.OPTION_MAY_RESUME If set to true, the SGD server will resume an existing session for the application rather than launch a new one. If there are no existing sessions, a new instance will be launched.
IConstants.OPTION_FQN If set to true, the SGD server will only accept fully-qualified application names. If not set, or set to false, the Secure Global Desktop server will attempt to identify the application uniquely from the supplied name and will only launch it if it is unique.
IConstants.OPTION_SESSION_NAME An optional friendly-name for the application session.
and attributes defined in the schema...
Returns:
Useful information is returned in attributes of the top-level object They are:
ISchemaNames.SESSION_IDThe ID of the application session. This is needed to perform other web service operations on the session.
IAttributeNames.TCCCONNECTIONFlag indicating whether the SGD Client is connected (true) or not (false). If the SGD Client is not connected, the launch request will be stored in the SGD server until an SGD Client is started.
ISchemaNames.APPLICATION_PLACEMENT Deprecated

 Sample response:
 <?xml version="1.0" encoding="UTF-8"?>
 <tta:response xmlns:tta="http://xml.tarantella.com/2001/soapreply.xsd">
  <attr name="scottaapplicationplacement">awtwindow</attr>
  <attr name="scottasessionid">server.uk.sun.com:1195116253260:-3013416157188449871:Li4uL19lbnMvbz1UYXJhbnRlbGxhIFN5c3RlbSBPYmplY3RzL2NuPUFkbWluaXN0cmF0b3I=</attr>
  <attr name="tccconnection">true</attr>
 </tta:response>
 
Throws:
java.rmi.RemoteException - On receipt of a SOAP fault.
Since:
1.0

startSessionInPlace

@Deprecated
java.lang.String startSessionInPlace(java.lang.String sessionCookie,
                                                java.lang.String applicationName,
                                                java.lang.String launcherId,
                                                Item[] launchOptions)
                                     throws java.rmi.RemoteException
Deprecated. This API behaves identically to startSession(String, String, Item[]).

Throws:
java.rmi.RemoteException

suspendSession

java.lang.String suspendSession(java.lang.String sessionCookie,
                                java.lang.String emulatorSessionId)
                                throws java.rmi.RemoteException
Suspends an application session. Administrators may suspend sessions belonging to any user, other users may only suspend their own. Suspending sessions with "never" resumability ends them.

Parameters:
sessionCookie - Identifies the user session performing the operation.
emulatorSessionId - Identifies the application session.
Returns:
An empty top-level object
Throws:
java.rmi.RemoteException - On receipt of a SOAP fault.
Since:
1.0

Oracle Secure Global Desktop Web Services API Documentation
Release 4.7

E21396-02

Copyright © 2012, 2013, Oracle and/or its affiliates. All rights reserved.