|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.buildforge.services.common.api.APIConnection
com.buildforge.services.client.api.APIClientConnection
public class APIClientConnection
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 |
---|
public static final java.lang.String DEFAULT_HOST
public static final int DEFAULT_PORT
Constructor Detail |
---|
public APIClientConnection() throws java.io.IOException
APIClientConnection(String, int)
using
DEFAULT_HOST
for the hostname and DEFAULT_PORT
for
the port number.
java.io.IOException
- if an I/O error occurspublic APIClientConnection(java.lang.String hostname) throws java.io.IOException
hostname
- the hostname for the connection, or null to
use the default hostname
.
java.io.IOException
- if an I/O error occurspublic APIClientConnection(java.lang.String hostname, int port) throws java.io.IOException
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.
java.io.IOException
- if an I/O error occursMethod Detail |
---|
public java.util.List<MessageDBO> getInfo()
public APIClientConnection request(int cmd) throws java.io.IOException
cmd
- the command ID, as defined in APIConstants
java.io.IOException
- if an I/O error occurspublic int as(int as)
public APIRequest call() throws java.io.IOException, ServiceException
Both IOException and ProtocolException
.
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 requestspublic java.lang.String authUser(java.lang.String username, java.lang.String password) throws java.io.IOException, ServiceException
authUser(String, String, String)
with a null
value for domain.
username
- the user that is authenticatingpassword
- the login password for the user
java.io.IOException
- if an I/O error occurs
ServiceException
- if the login request failspublic java.lang.String authUser(java.lang.String username, java.lang.String password, java.lang.String domain) throws java.io.IOException, ServiceException
username
- the user that is authenticatingpassword
- the login password for the userdomain
- the LDAP domain to authenticate against, or
null if no LDAP domain is used
java.io.IOException
- if an I/O error occurs
ServiceException
- if the login request failspublic APIClientConnection authToken(java.lang.String token) throws java.io.IOException, ServiceException
token
- the login token from a previously created session
java.io.IOException
- if an I/O error occurs
ServiceException
- if the login request failspublic void logout() throws java.io.IOException, ServiceException
java.io.IOException
ServiceException
public java.lang.Object ping(java.lang.Object value) throws java.io.IOException, ServiceException
value
- the value to send
java.io.IOException
ServiceException
public java.lang.String getLocale() throws java.io.IOException, ServiceException
java.io.IOException
ServiceException
public void setLocale(java.lang.String locale) throws java.io.IOException, ServiceException
locale
- the new locale setting
java.io.IOException
ServiceException
public java.lang.String getTimeZone() throws java.io.IOException, ServiceException
java.io.IOException
ServiceException
public void setTimeZone(java.lang.String tzone) throws java.io.IOException, ServiceException
tzone
- the new time zone setting
java.io.IOException
ServiceException
public java.lang.String translate(MessageDBO msg) throws java.io.IOException, ServiceException
msg
- the message to be translated
java.io.IOException
ServiceException
public java.lang.String translate(MessageDBO msg, java.lang.String locale, java.lang.String tzone) throws java.io.IOException, ServiceException
msg
- the message to be translatedlocale
- the ICU library identifier for the desired locale, or
null to use the connection's default localetzone
- the ICU library identifier for the desired time zone, or
null to use the connection's default time zone
java.io.IOException
ServiceException
public java.lang.String render(MessageDBO msg)
Localizer
render
in interface Localizer
msg
- the message to localize
public void close() throws java.io.IOException
APIConnection
close
in class APIConnection
java.io.IOException
- if an I/O error occurs
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |