com.buildforge.services.client.api
Class APIClientConnection

java.lang.Object
  extended by com.buildforge.services.common.api.APIConnection
      extended by com.buildforge.services.client.api.APIClientConnection
All Implemented Interfaces:
Localizer
Direct Known Subclasses:
SecureAPIClientConnection

public class APIClientConnection
extends APIConnection
implements Localizer

This class implements the basic interaction of an API client with the underlying connection. This class should be used to establish a new connection and to set global session information, such as the desired locale, time zone, and user authentication data.

Unlike previous the previous API implementations that Build Forge has provided, the services layer does not normally connect through the web server. Instead, it listens for connections on its own dedicated port. When the port is not specified in the connection request, the DEFAULT_PORT is used.

Instances of this class may be used as the system message localizer. See Localizer for more information. If the caller has not explicitly configured an alternate localizer, then the first client connection that is successfully established is set as the localizer. If that client connection fails, it is the caller's responsibility to configure a new localizer; otherwise, localization will fall back on Localizer.Generic.

Typically, services layer calls are made by requesting functionality from one of the classes in com.buildforge.services.client.dbo. For example, the following code snippet finds all scheduled builds whose names begin with "DELETE_ME_" and deletes them:

                APIClientConnection conn = new APIClientConnection();
                List<Cron> list =
                                Cron.findAll(conn);
                for (Cron cron : list) {
                        String desc = cron.getDescription();
                        if (desc.startsWith("DELETE_ME_")) {
                                try {
                                        cron.delete();
                                } catch (ServiceException se) {
                                        System.err.println(
                                                "Error deleting scheduler entry '" + desc + "': " + se);
                                }
                        }
                }
 

In addition to basic connection and session management, this class also implements the low-level calls for sending request information to the server. These are intended for use by the services layer itself, not for general consumption by end users, and their direct use is therefore discouraged. Reckless use of them may produce a ProtocolException, which permanently invalidates any connection on which it occurs.

The low-level methods are request(int), call(), and the various writeEntry methods. The low-level version of creating a user looks something like this:

 public APIRequest createUser({APIClientConnection conn) {
                conn.request(COMMAND_USER_ADD);
                conn.writeEntry("user", user);
                return conn.call();
 }
 


Nested Class Summary
 
Nested classes/interfaces inherited from interface com.buildforge.services.common.text.Localizer
Localizer.Generic
 
Field Summary
static java.lang.String DEFAULT_HOST
          The default hostname to use when none is provided.
static int DEFAULT_PORT
          The default port number to use when none is provided.
 
Constructor Summary
APIClientConnection()
          Creates a new connection object for implementing the client side of an API connection using default connection parameters.
APIClientConnection(java.lang.String hostname)
          Creates a new connection object for implementing the client side of an API connection using the specified hostname and the default port.
APIClientConnection(java.lang.String hostname, int port)
          Creates a new connection object for implementing the client side of an API connection using the specified hostname and port.
 
Method Summary
 int as(int as)
          Contexts authenticated as SYSTEM are able to take actions on behalf of other users.
 APIClientConnection authToken(java.lang.String token)
          Authenticates the connection.
 java.lang.String authUser(java.lang.String username, java.lang.String password)
          Authenticates the connection.
 java.lang.String authUser(java.lang.String username, java.lang.String password, java.lang.String domain)
          Authenticates the connection.
 APIRequest call()
          Complete the current request, receive the response to it, and return that response to the caller.
 void close()
          Closes this connection.
 java.util.List<MessageDBO> getInfo()
          Returns the audit events that have been recorded for this event.
 java.lang.String getLocale()
          Asks the server for the locale this connection is using.
 java.lang.String getTimeZone()
          Asks the server for the time zone this connection is using.
 void logout()
          Give up the connection's current authentication credentials.
 java.lang.Object ping(java.lang.Object value)
          Request that a piece of data be sent to the server, which is expected to return it.
 java.lang.String render(MessageDBO msg)
          Localize the message to a string, if possible.
 APIClientConnection request(int cmd)
          Begins a new request.
 void setLocale(java.lang.String locale)
          Changes the locale setting for the current connection.
 void setTimeZone(java.lang.String tzone)
          Changes the time zone setting for the current connection.
 java.lang.String translate(MessageDBO msg)
          Requests message translation using the connection's default locale and time zone.
 java.lang.String translate(MessageDBO msg, java.lang.String locale, java.lang.String tzone)
          Requests message translation using an arbitrary locale and time zone.
 
Methods inherited from class com.buildforge.services.common.api.APIConnection
check, getProtocol, readRequest, setProtocol, writeEntry, writeEntry, writeEntry, writeEntry, writeEntry, writeEntry, writeEntry, writeEntry, writeEntry, writeEntry, writeEntry, writeEntry, writeEntry, writeEntry, writeFooter, writeHeader
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_HOST

public static final java.lang.String DEFAULT_HOST
The default hostname to use when none is provided. The value of this constant is "localhost".

See Also:
Constant Field Values

DEFAULT_PORT

public static final int DEFAULT_PORT
The default port number to use when none is provided. The value of this constant is 3966.

See Also:
Constant Field Values
Constructor Detail

APIClientConnection

public APIClientConnection()
                    throws java.io.IOException
Creates a new connection object for implementing the client side of an API connection using default connection parameters. This is exactly equivalent to APIClientConnection(String, int) using DEFAULT_HOST for the hostname and DEFAULT_PORT for the port number.

Throws:
java.io.IOException - if an I/O error occurs

APIClientConnection

public APIClientConnection(java.lang.String hostname)
                    throws java.io.IOException
Creates a new connection object for implementing the client side of an API connection using the specified hostname and the default port.

Parameters:
hostname - the hostname for the connection, or null to use the default hostname.
Throws:
java.io.IOException - if an I/O error occurs

APIClientConnection

public APIClientConnection(java.lang.String hostname,
                           int port)
                    throws java.io.IOException
Creates a new connection object for implementing the client side of an API connection using the specified hostname and port.

Parameters:
hostname - the hostname for the connection, or null to use the default hostname.
port - the port number for the connection, or non-positive value to use the default port. Note that this is NOT the web server port, but rather a dedicated port that is used only by the services layer.
Throws:
java.io.IOException - if an I/O error occurs
Method Detail

getInfo

public java.util.List<MessageDBO> getInfo()
Returns the audit events that have been recorded for this event.


request

public APIClientConnection request(int cmd)
                            throws java.io.IOException
Begins a new request. If a previous request is already in process, then that previous request is aborted.

Parameters:
cmd - the command ID, as defined in APIConstants
Returns:
this object, for convenience
Throws:
java.io.IOException - if an I/O error occurs

as

public int as(int as)
Contexts authenticated as SYSTEM are able to take actions on behalf of other users. This sets the identity to use for future requests. Use UID_SYSTEM to restore SYSTEM access. This setting should not be changed for standard user connections, as the system will not allow user contexts to change their identity.


call

public APIRequest call()
                throws java.io.IOException,
                       ServiceException
Complete the current request, receive the response to it, and return that response to the caller.

Both IOException and ProtocolException.

Returns:
the decoded response
Throws:
java.io.IOException - if an I/O error occurs. This indicates that an error has occurred at the network layer and that the connection should be closed.
ProtocolException - if a protocol violation occurs. This indicates that the protocol stream between the client and the server has been corrupted and that the connection should be closed.
ServiceException - if an error occurs while processing the request, but the connection is still in a valid state and may be reused for additional requests

authUser

public java.lang.String authUser(java.lang.String username,
                                 java.lang.String password)
                          throws java.io.IOException,
                                 ServiceException
Authenticates the connection. This should generally be done immediately after creating the connection, before any other commands are issued. This is a convenience method that calls authUser(String, String, String) with a null value for domain.

Parameters:
username - the user that is authenticating
password - the login password for the user
Returns:
the login token returned by the services layer
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the login request fails

authUser

public java.lang.String authUser(java.lang.String username,
                                 java.lang.String password,
                                 java.lang.String domain)
                          throws java.io.IOException,
                                 ServiceException
Authenticates the connection. This should generally be done immediately after creating the connection, before any other commands are issued.

Parameters:
username - the user that is authenticating
password - the login password for the user
domain - the LDAP domain to authenticate against, or null if no LDAP domain is used
Returns:
the login token returned by the services layer
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the login request fails

authToken

public APIClientConnection authToken(java.lang.String token)
                              throws java.io.IOException,
                                     ServiceException
Authenticates the connection. This should generally be done immediately after creating the connection, before any other commands are issued.

Parameters:
token - the login token from a previously created session
Returns:
this connection, for convenience
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the login request fails

logout

public void logout()
            throws java.io.IOException,
                   ServiceException
Give up the connection's current authentication credentials.

Throws:
java.io.IOException
ServiceException

ping

public java.lang.Object ping(java.lang.Object value)
                      throws java.io.IOException,
                             ServiceException
Request that a piece of data be sent to the server, which is expected to return it.

Parameters:
value - the value to send
Returns:
the same value, as reported by the server. Note that for some objects (database objects in particular), the server may not always report the same information that was sent to it. The only values that should definitely come back exactly as they were sent are String values and null.
Throws:
java.io.IOException
ServiceException

getLocale

public java.lang.String getLocale()
                           throws java.io.IOException,
                                  ServiceException
Asks the server for the locale this connection is using.

Returns:
the current ICU locale identification string
Throws:
java.io.IOException
ServiceException

setLocale

public void setLocale(java.lang.String locale)
               throws java.io.IOException,
                      ServiceException
Changes the locale setting for the current connection. The value specified for the locale should be one of the locale identifiers supported by the ICU library.

Parameters:
locale - the new locale setting
Throws:
java.io.IOException
ServiceException

getTimeZone

public java.lang.String getTimeZone()
                             throws java.io.IOException,
                                    ServiceException
Asks the server for the time zone this connection is using.

Returns:
the current ICU time zone identification string
Throws:
java.io.IOException
ServiceException

setTimeZone

public void setTimeZone(java.lang.String tzone)
                 throws java.io.IOException,
                        ServiceException
Changes the time zone setting for the current connection. The value specified for the time zone should be one of the time zone identifiers supported by the ICU library.

Parameters:
tzone - the new time zone setting
Throws:
java.io.IOException
ServiceException

translate

public java.lang.String translate(MessageDBO msg)
                           throws java.io.IOException,
                                  ServiceException
Requests message translation using the connection's default locale and time zone.

Parameters:
msg - the message to be translated
Returns:
the translated message
Throws:
java.io.IOException
ServiceException

translate

public java.lang.String translate(MessageDBO msg,
                                  java.lang.String locale,
                                  java.lang.String tzone)
                           throws java.io.IOException,
                                  ServiceException
Requests message translation using an arbitrary locale and time zone.

Parameters:
msg - the message to be translated
locale - the ICU library identifier for the desired locale, or null to use the connection's default locale
tzone - the ICU library identifier for the desired time zone, or null to use the connection's default time zone
Returns:
the translated message
Throws:
java.io.IOException
ServiceException

render

public java.lang.String render(MessageDBO msg)
Description copied from interface: Localizer
Localize the message to a string, if possible.

Specified by:
render in interface Localizer
Parameters:
msg - the message to localize
Returns:
the localized string, or null if the message could not be successfully localized

close

public void close()
           throws java.io.IOException
Description copied from class: APIConnection
Closes this connection.

Overrides:
close in class APIConnection
Throws:
java.io.IOException - if an I/O error occurs