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

static class	RestSession.FORMAT
static class	RestSession.PARTITION

Field Summary

static java.lang.String

CLASS_VERSION Class version string

Method Summary

protected 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.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	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	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	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

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

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

createHttpConnection

protected 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