atg.rest.client

Class RestSession

java.lang.Object

atg.rest.client.RestSession

public class RestSession
extends java.lang.Object

A class which represents a session with an ATG server.

To obtain an anonymous (i.e. not logged in) session: RestSession session = RestSession.createSession(host, port); session.startSession(); [make REST calls here] optionally, if you decide to login later: session.login(username, password); session.logout();

To obtain a session that's logged in: RestSession session = RestSession.createSession(host, port, username, password); session.login(); [make REST calls here] session.logout();

Below is a sample application which demonstrates the basic use of this client library.

 
                
        import atg.rest.client.RestClientException;
        import atg.rest.client.RestComponentHelper;
        import atg.rest.client.RestResult;
        import atg.rest.client.RestSession;
 
        import java.io.IOException;
 
        public class RestClientSample {
          private String mUsername = null;
          private String mPassword = null;
          private String mHost = "localhost";
          private int mPort = 80;
          private RestSession mSession = null;
 
          public RestClientSample() {}
 
          protected void parseArguments(String[] pArgs) throws Exception {
            for (int i = 0; i < pArgs.length; i++) {
              String arg = pArgs[i];
 
              if (arg.equals("-user"))
                mUsername = pArgs[i+1];
              else if (arg.equals("-password"))
                mPassword = pArgs[i+1];
              else if (arg.equals("-host"))
                mHost = pArgs[i+1];
              else if (arg.equals("-port"))
                mPort = Integer.parseInt(pArgs[i+1]);
            }
 
            if (isBlank(mUsername))
              throw new Exception("Must supply username");
            if (isBlank(mPassword))
              throw new Exception("Must supply password");
          }
 
          protected boolean isBlank(String pStr) {
            return (pStr == null || pStr.length() == 0 || pStr.trim().length() == 0);
          }
 
          protected void println(String s) {
            System.out.println(s);
          }
 
          protected void println(Throwable t) {
            t.printStackTrace(System.out);
          }
 
          protected void execute() throws RestClientException {
            mSession = RestSession.createSession(mHost, mPort, mUsername, mPassword);
            mSession.setUseHttpsForLogin(false);
 
            try {
              mSession.login();
              println("Login Successful");
              
              // add REST requests here
            }
            catch (Throwable t) {
              println(t);
            }
            finally {
              try {
                mSession.logout();
                println("Logout Successful");
              }
              catch (RestClientException e) {
                println(e);
              }
            }
          }
 
          public static void main(String[] args) {
            RestClientSample sample = new RestClientSample();
 
            try {
              sample.parseArguments(args);
              sample.execute();
            }
            catch (Throwable t) {
              sample.println(t);
            }
          }
        }
        
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	RestSession.ConnectionAwareWeakReference<T> A class representing a very specialised form of weak refernece which, in addition to the expected reference, also contains a regular reference to a connection.
static class	RestSession.FORMAT
static class	RestSession.PARTITION

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CLASS_VERSION Class version string

Method Summary

Modifier and Type	Method and Description
protected void	clearOrphanedConnections() Clear any remaining connections which have been orphaned.
java.net.HttpURLConnection	createHttpConnection(java.lang.String pURL, java.lang.Object pParams, java.lang.String pMethodType) Creates an http connection to the server with the given URL and parameters.
RestResult	createHttpRequest(java.lang.String pURL, java.util.Map<java.lang.String,java.lang.Object> pParams, java.lang.Object[] pArguments, java.lang.String pMethodType) Raw method for creating an http request.
RestResult	createHttpRequest(java.lang.String pURL, java.util.Map<java.lang.String,java.lang.Object> pParams, java.lang.String pMethodType) Raw method for creating an http request.
static RestSession	createSession(java.lang.String pHost, int pPort) Factory method for creating RestSession
static RestSession	createSession(java.lang.String pHost, int pPort, RestSession.PARTITION pPartitionType, java.lang.String pPartitionId) Factory method for creating RestSession
static RestSession	createSession(java.lang.String pHost, int pPort, java.lang.String pUsername, java.lang.String pPassword) Factory method for creating RestSession
static RestSession	createSession(java.lang.String pHost, int pPort, java.lang.String pUsername, java.lang.String pPassword, RestSession.PARTITION pPartitionType, java.lang.String pPartitionId) Factory method for creating RestSession
java.net.HttpURLConnection	getConnection() Returns the connection for the most recent RestResult associated with this RestSession, if one is available.
java.util.Set<java.lang.String>	getCookieFields() Retrieves the value of the cookie fields which will be sent with every request if resend cookie is set.
java.lang.String	getEncoding()
java.lang.String	getHost()
java.lang.String	getHostString() Returns a host string for this session object of the format scheme://host:port.
RestSession.FORMAT	getInputFormat() Returns the value of the default input format on the server.
RestSession.FORMAT	getOutputFormat() Returns the value of the default output format on the server.
java.lang.String	getPartitionId() get PartitionId
RestSession.PARTITION	getPartitionType() get PartitionType
java.lang.String	getPassword()
int	getPort()
java.lang.String	getRestContextRoot()
java.lang.String	getScheme()
java.lang.String	getSessionId()
java.lang.String	getUserId()
java.lang.String	getUsername()
boolean	isResendCookie() Retrieve a flag stating whether the cookies defined by 'cookie fields' should be sent with each request.
boolean	isUseHttpsForLogin()
boolean	isUseInternalProfileForLogin()
java.lang.String	login() Logs the specified user into the specified server.
java.lang.String	login(java.lang.String pUsername, java.lang.String pPassword) Logs the specified user into the already specified server.
RestResult	logout() Logs the specified user out of the specified server.
protected java.lang.Object	packageParameters(java.util.Map<java.lang.String,java.lang.Object> pParams, java.lang.Object[] pArguments, java.lang.String pMethodType) This method packages parameters in either a JSON object, XML document, or parameter map depending on the setting in Session.mInputFormat
void	setCookieFields(java.util.Set<java.lang.String> pCookieFields) Sets the value of the cookie fields which will be sent with every request if resend cookie is set.
void	setEncoding(java.lang.String pEncoding)
void	setHost(java.lang.String pHost)
void	setInputFormat(RestSession.FORMAT pInputFormat)
void	setOutputFormat(RestSession.FORMAT pOutputFormat)
void	setPartitionId(java.lang.String pPartitionId) set PartitionId
void	setPartitionType(RestSession.PARTITION pPartitionType) set PartitionType
void	setPassword(java.lang.String pPassword)
void	setPort(int pPort)
void	setResendCookie(boolean pResendCookie) Set a flag stating whether the cookies defined by 'cookie fields' should be sent with each request.
void	setRestContextRoot(java.lang.String pRestContextRoot)
void	setScheme(java.lang.String pScheme)
void	setSessionId(java.lang.String pSessionId)
void	setUseHttpsForLogin(boolean pUseHttpsForLogin)
void	setUseInternalProfileForLogin(boolean pUseInternalProfileForLogin)
protected void	setUserId(java.lang.String pUserId)
void	setUsername(java.lang.String pUsername)
void	startSession() Initializes the RestSession without actually logging in.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CLASS_VERSION

public static java.lang.String CLASS_VERSION

Class version string

Method Detail

getConnection

public java.net.HttpURLConnection getConnection()

Returns the connection for the most recent RestResult associated with this RestSession, if one is available.

Returns:

The HttpURLConnection object is returned if it's available. As the RestSession itself only maintains a weak reference to the RestResult, if the caller has not kept a reference to the RestResult then this method could return null even if at some point there was a RestResult.

getHost

public java.lang.String getHost()

Returns:

the value of host

setHost

public void setHost(java.lang.String pHost)

Parameters:

pHost - the host to set

getPort

public int getPort()

Returns:

the value of port

setPort

public void setPort(int pPort)

Parameters:

pPort - the port to set

getUsername

public java.lang.String getUsername()

Returns:

the value of pUsername

setUsername

public void setUsername(java.lang.String pUsername)

Parameters:

pUsername - the pUsername to set

getPassword

public java.lang.String getPassword()

Returns:

the value of password

setPassword

public void setPassword(java.lang.String pPassword)

Parameters:

pPassword - the password to set

setPartitionId

public void setPartitionId(java.lang.String pPartitionId)

set PartitionId

Parameters:

pPartitionId - the PartitionId

getPartitionId

public java.lang.String getPartitionId()

get PartitionId

Returns:

the PartitionId

setPartitionType

public void setPartitionType(RestSession.PARTITION pPartitionType)

set PartitionType

Parameters:

pPartitionType - the PartitionType

getPartitionType

public RestSession.PARTITION getPartitionType()

get PartitionType

Returns:

the PartitionType

getScheme

public java.lang.String getScheme()

Returns:

the value of scheme. Default is http

setScheme

public void setScheme(java.lang.String pScheme)

Parameters:

pScheme - the scheme to set

getRestContextRoot

public java.lang.String getRestContextRoot()

Returns:

the value of restContextRoot

setRestContextRoot

public void setRestContextRoot(java.lang.String pRestContextRoot)

Parameters:

pRestContextRoot - the restContextRoot to set

isUseInternalProfileForLogin

public boolean isUseInternalProfileForLogin()

Returns:

the value of useInternalProfileForLogin

setUseInternalProfileForLogin

public void setUseInternalProfileForLogin(boolean pUseInternalProfileForLogin)

Parameters:

pUseInternalProfileForLogin - the useInternalProfileForLogin to set

isUseHttpsForLogin

public boolean isUseHttpsForLogin()

Returns:

the value of useHttpsForLogin

setUseHttpsForLogin

public void setUseHttpsForLogin(boolean pUseHttpsForLogin)

Parameters:

pUseHttpsForLogin - the useHttpsForLogin to set

getUserId

public java.lang.String getUserId()

Returns:

the value of userId

setUserId

protected void setUserId(java.lang.String pUserId)

Parameters:

pUserId - the userId to set

isResendCookie

public boolean isResendCookie()

Retrieve a flag stating whether the cookies defined by 'cookie fields' should be sent with each request.

Returns:

Boolean stating whether or not to resend the cookies each time.

setResendCookie

public void setResendCookie(boolean pResendCookie)

Set a flag stating whether the cookies defined by 'cookie fields' should be sent with each request.

setCookieFields

public void setCookieFields(java.util.Set<java.lang.String> pCookieFields)

Sets the value of the cookie fields which will be sent with every request if resend cookie is set.

getCookieFields

public java.util.Set<java.lang.String> getCookieFields()

Retrieves the value of the cookie fields which will be sent with every request if resend cookie is set.

Returns:

A set of cookie field strings.

getSessionId

public java.lang.String getSessionId()

Returns:

the value of sessionId

setSessionId

public void setSessionId(java.lang.String pSessionId)

Parameters:

pSessionId - the sessionId to set

getEncoding

public java.lang.String getEncoding()

Returns:

the value of encoding

setEncoding

public void setEncoding(java.lang.String pEncoding)

Parameters:

pEncoding - the encoding to set

getInputFormat

public RestSession.FORMAT getInputFormat()

Returns the value of the default input format on the server. Note that changing the value of this property has no effect on the format the server expects.

Returns:

the value of inputFormat

setInputFormat

public void setInputFormat(RestSession.FORMAT pInputFormat)

Parameters:

pInputFormat - the inputFormat to set

getOutputFormat

public RestSession.FORMAT getOutputFormat()

Returns the value of the default output format on the server. Note that changing this format does not change the format of data returned from the server.

Returns:

the value of outputFormat

setOutputFormat

public void setOutputFormat(RestSession.FORMAT pOutputFormat)

Parameters:

pOutputFormat - the outputFormat to set

createSession

public static RestSession createSession(java.lang.String pHost,
                                        int pPort,
                                        java.lang.String pUsername,
                                        java.lang.String pPassword)

Factory method for creating RestSession

Parameters:

pHost - the host to connect to

pPort - the port the server is listening on

pUsername - the username

pPassword - the user's password

Returns:

a new RestSession object

createSession

public static RestSession createSession(java.lang.String pHost,
                                        int pPort,
                                        java.lang.String pUsername,
                                        java.lang.String pPassword,
                                        RestSession.PARTITION pPartitionType,
                                        java.lang.String pPartitionId)

Factory method for creating RestSession

Parameters:

pHost - the host to connect to

pPort - the port the server is listening on

pUsername - the username

pPassword - the user's password

pPartitionType - must be one of PARTITION.SITE or PARTITION.PROFILE_REALM

pPartitionId - either the site id or realm id

Returns:

a new RestSession object

createSession

public static RestSession createSession(java.lang.String pHost,
                                        int pPort)

Factory method for creating RestSession

Parameters:

pHost - the host to connect to

pPort - the port the server is listening on

Returns:

a new RestSession Object

createSession

public static RestSession createSession(java.lang.String pHost,
                                        int pPort,
                                        RestSession.PARTITION pPartitionType,
                                        java.lang.String pPartitionId)

Factory method for creating RestSession

Parameters:

pHost - the host to connect to

pPort - the port the server is listening on

pPartitionType - must be one of PARTITION.SITE or PARTITION.PROFILE_REALM

pPartitionId - either the site id or realm id

Returns:

a new RestSession Object

login

public java.lang.String login(java.lang.String pUsername,
                              java.lang.String pPassword)
                       throws RestClientException

Logs the specified user into the already specified server. It is not necessary to call startSession() before this method.

Parameters:

pUsername - the username

pPassword - the user's password

Returns:

the userId of the logged in user

Throws:

RestClientException - if an error occurs issuing the request

login

public java.lang.String login()
                       throws RestClientException

Logs the specified user into the specified server. It is not necessary to call startSession() before this method.

Returns:

the userId of the logged in user

Throws:

RestClientException - if an error occurs issuing the request

startSession

public void startSession()
                  throws RestClientException

Initializes the RestSession without actually logging in. You must call this method or login() before using the session. Sets the session confirmation number, session id, and the default input/output customizers. You can later call login(String, String) after this method to log the session in.

Throws:

RestClientException

logout

public RestResult logout()
                  throws RestClientException

Logs the specified user out of the specified server.

Returns:

the result of the logout operation

Throws:

RestClientException - if an error occurs issuing the request

clearOrphanedConnections

protected void clearOrphanedConnections()

Clear any remaining connections which have been orphaned.

createHttpConnection

public java.net.HttpURLConnection createHttpConnection(java.lang.String pURL,
                                                       java.lang.Object pParams,
                                                       java.lang.String pMethodType)
                                                throws RestClientException,
                                                       java.io.IOException

Creates an http connection to the server with the given URL and parameters.

Parameters:

pURL - the url to request

pParams - any parameters for the request

pMethodType - the request type: GET, POST, PUT, or DELETE

Returns:

a java.net.HttpURLConnection object

Throws:

RestClientException - if any of the parameters cannot be converted

java.io.IOException - if an IO error occurs

createHttpRequest

public RestResult createHttpRequest(java.lang.String pURL,
                                    java.util.Map<java.lang.String,java.lang.Object> pParams,
                                    java.lang.String pMethodType)
                             throws RestClientException

Raw method for creating an http request.

Parameters:

pURL - the URL

pParams - any url parameters required

pMethodType - the http method type

Returns:

a RestResult object

Throws:

RestClientException - if any of the parameters cannot be converted

createHttpRequest

public RestResult createHttpRequest(java.lang.String pURL,
                                    java.util.Map<java.lang.String,java.lang.Object> pParams,
                                    java.lang.Object[] pArguments,
                                    java.lang.String pMethodType)
                             throws RestClientException

Raw method for creating an http request.

Parameters:

pURL - the URL

pParams - any url parameters required

pArguments - an array of arguments to be passed to for a method call or null if there are no arguments

pMethodType - the http method type

Returns:

a RestResult object

Throws:

RestClientException - if any of the parameters cannot be converted

packageParameters

protected java.lang.Object packageParameters(java.util.Map<java.lang.String,java.lang.Object> pParams,
                                             java.lang.Object[] pArguments,
                                             java.lang.String pMethodType)
                                      throws RestClientException

This method packages parameters in either a JSON object, XML document, or parameter map depending on the setting in Session.mInputFormat

Parameters:

pParams - the parameter map

pArguments - the argument list when executing a method, null otherwise

pMethodType - the http method type

Returns:

either a Map, a JSONObject, or a Document depending on the input format

Throws:

RestClientException - if an error occurs issuing the request

getHostString

public java.lang.String getHostString()

Returns a host string for this session object of the format scheme://host:port. Example http://localhost:80

Returns:

a host string