com.buildforge.services.common.api
Class APIConnection

java.lang.Object
  extended by com.buildforge.services.common.api.APIConnection
Direct Known Subclasses:
APIClientConnection

public abstract class APIConnection
extends java.lang.Object

The APIConnection class is responsible for the encoding and decoding of API requests, thereby implementing the line protocol of the services layer. This is a brief summary of that protocol.


Constructor Summary
APIConnection(IBufferedConnection conn)
          Attaches the API protocol to a buffered connection.
 
Method Summary
 void check()
          Checks whether or not this connection has been invalidated due to a violation of the protocol.
 void close()
          Closes this connection.
 Protocol getProtocol()
          Returns the protocol that this connection will bind at the time of the first request, or the bound protocol type if one has already been bound.
 APIRequest readRequest(boolean isServer)
          Runs the request decoder.
 boolean setProtocol(Protocol protocol)
          Sets the preferred protocol for this connection, if possible.
 void writeEntry(java.lang.String key, java.util.BitSet value)
          Write a data entry that is a bit set to the current API request.
 void writeEntry(java.lang.String key, boolean value)
          Write a data entry that is a char to the current API request.
 void writeEntry(java.lang.String key, char value)
          Write a data entry that is a char to the current API request.
 void writeEntry(java.lang.String key, java.util.Collection<?> value)
          Write a data entry that is a Collector to the current API request.
 void writeEntry(java.lang.String key, DBObject value)
          Write a data entry that is a DataBase Object (DBO) to the current API request.
 void writeEntry(java.lang.String key, double value)
          Write a data entry that is a double to the current API request.
 void writeEntry(java.lang.String key, java.lang.Enum<?> value)
          Write a data entry that is an enumerated type to the current API request.
 void writeEntry(java.lang.String key, int value)
          Write a data entry that is an int to the current API request.
 void writeEntry(java.lang.String key, long value)
          Write a data entry that is a long to the current API request.
 void writeEntry(java.lang.String key, java.util.Map<?,?> value)
          Write a data entry that is a map to the current API request.
 void writeEntry(java.lang.String key, java.lang.Number value)
          Write a data entry that is a number object to the current API request.
 void writeEntry(java.lang.String key, java.lang.Object obj)
          Write a data entry of unknown type to the current API request.
 void writeEntry(java.lang.String key, java.lang.Object[] value)
          Write a data entry that is an array to the current API request.
 void writeEntry(java.lang.String key, java.lang.String value)
          Write a data entry that is a string to the current API request.
 void writeFooter()
          Completes an active response, including flushing it to the connection.
 void writeHeader(int cmd, int as)
          Begins an active request or response.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

APIConnection

public APIConnection(IBufferedConnection conn)
Attaches the API protocol to a buffered connection.

Parameters:
conn - the buffered connection to wrap with API connection logic
Method Detail

check

public void check()
           throws java.io.IOException
Checks whether or not this connection has been invalidated due to a violation of the protocol. If the connection has not yet bound a protocol, or if the connection is still valid, then this method has no effect.

Throws:
java.io.IOException - if the connection been invalidated

getProtocol

public Protocol getProtocol()
Returns the protocol that this connection will bind at the time of the first request, or the bound protocol type if one has already been bound.

Returns:
the protocol, or null if the connection does not yet have a protocol bound to it and no specific protocol has been requested with setProtocol(Protocol).

setProtocol

public boolean setProtocol(Protocol protocol)
Sets the preferred protocol for this connection, if possible. The protocol setting may be changed freely until the protocol has been bound. After that, the protocol may not be changed. The protocol will normally be bound the first time a request is sent by the client.

Parameters:
protocol - the protocol that is desired, or null to revert to the default protocol choice
Returns:
true if the request is permitted, or false if the protocol is already bound. In the latter case, getProtocol() may be used to determine which protocol is being used. Note that false is returned even if the bound protocol happens to be the same as the requested one.

close

public void close()
           throws java.io.IOException
Closes this connection.

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

writeHeader

public void writeHeader(int cmd,
                        int as)
                 throws java.io.IOException
Begins an active request or response. If there is already a request in progress, it is aborted.

Parameters:
cmd - the command type
Throws:
java.io.IOException - if an I/O error occurs

writeFooter

public void writeFooter()
                 throws java.io.IOException,
                        ProtocolException
Completes an active response, including flushing it to the connection.

Throws:
java.io.IOException - if an I/O error occurs
ProtocolException - if no request frame has been started

writeEntry

public void writeEntry(java.lang.String key,
                       java.lang.Object obj)
                throws java.io.IOException
Write a data entry of unknown type to the current API request.

Parameters:
key - the key to use for this entry. This may only contain ASCII characters.
obj - the value to assign to the key
Throws:
java.io.IOException - if an I/O error occurs

writeEntry

public void writeEntry(java.lang.String key,
                       java.util.BitSet value)
                throws java.io.IOException
Write a data entry that is a bit set to the current API request. The bit set should be written as though it were a list of integers.

Parameters:
key - as for writeEntry(String, Object)
value - the value to assign to the key
Throws:
java.io.IOException - if an I/O error occurs

writeEntry

public void writeEntry(java.lang.String key,
                       java.lang.String value)
                throws java.io.IOException
Write a data entry that is a string to the current API request.

Parameters:
key - as for writeEntry(String, Object)
value - the value to assign to the key
Throws:
java.io.IOException - if an I/O error occurs

writeEntry

public void writeEntry(java.lang.String key,
                       java.lang.Number value)
                throws java.io.IOException
Write a data entry that is a number object to the current API request.

Parameters:
key - as for writeEntry(String, Object)
value - the value to assign to the key
Throws:
java.io.IOException - if an I/O error occurs

writeEntry

public void writeEntry(java.lang.String key,
                       java.lang.Enum<?> value)
                throws java.io.IOException
Write a data entry that is an enumerated type to the current API request.

Parameters:
key - as for writeEntry(String, Object)
value - the value to assign to the key
Throws:
java.io.IOException - if an I/O error occurs

writeEntry

public void writeEntry(java.lang.String key,
                       boolean value)
                throws java.io.IOException
Write a data entry that is a char to the current API request.

Parameters:
key - as for writeEntry(String, Object)
value - the value to assign to the key
Throws:
java.io.IOException - if an I/O error occurs

writeEntry

public void writeEntry(java.lang.String key,
                       char value)
                throws java.io.IOException
Write a data entry that is a char to the current API request.

Parameters:
key - as for writeEntry(String, Object)
value - the value to assign to the key
Throws:
java.io.IOException - if an I/O error occurs

writeEntry

public void writeEntry(java.lang.String key,
                       int value)
                throws java.io.IOException
Write a data entry that is an int to the current API request.

Parameters:
key - as for writeEntry(String, Object)
value - the value to assign to the key
Throws:
java.io.IOException - if an I/O error occurs

writeEntry

public void writeEntry(java.lang.String key,
                       long value)
                throws java.io.IOException
Write a data entry that is a long to the current API request.

Parameters:
key - as for writeEntry(String, Object)
value - the value to assign to the key
Throws:
java.io.IOException - if an I/O error occurs

writeEntry

public void writeEntry(java.lang.String key,
                       double value)
                throws java.io.IOException
Write a data entry that is a double to the current API request.

Parameters:
key - as for writeEntry(String, Object)
value - the value to assign to the key
Throws:
java.io.IOException - if an I/O error occurs

writeEntry

public void writeEntry(java.lang.String key,
                       java.lang.Object[] value)
                throws java.io.IOException
Write a data entry that is an array to the current API request.

Parameters:
key - as for writeEntry(String, Object)
value - the value to assign to the key
Throws:
java.io.IOException - if an I/O error occurs

writeEntry

public void writeEntry(java.lang.String key,
                       java.util.Collection<?> value)
                throws java.io.IOException
Write a data entry that is a Collector to the current API request.

Parameters:
key - as for writeEntry(String, Object)
value - the value to assign to the key
Throws:
java.io.IOException - if an I/O error occurs

writeEntry

public void writeEntry(java.lang.String key,
                       java.util.Map<?,?> value)
                throws java.io.IOException
Write a data entry that is a map to the current API request.

Parameters:
key - as for writeEntry(String, Object)
value - the value to assign to the key
Throws:
java.io.IOException - if an I/O error occurs

writeEntry

public void writeEntry(java.lang.String key,
                       DBObject value)
                throws java.io.IOException
Write a data entry that is a DataBase Object (DBO) to the current API request.

Parameters:
key - as for writeEntry(String, Object)
value - the value to assign to the key
Throws:
java.io.IOException - if an I/O error occurs

readRequest

public APIRequest readRequest(boolean isServer)
                       throws java.io.IOException,
                              ServiceException
Runs the request decoder. It will continue processing until it requires more input or throws a fatal exception. Once it a request is completed, it returns.

Parameters:
isServer - true if APIConstants.CTRL_AS should be accepted, which only the server should ever do.
Returns:
the decoded API request (or response), or null if the connection is idle
Throws:
java.io.IOException - if the connection is no longer usable because an I/O error has occurred
ProtocolException - if the connection is no longer usable because the communication stream contains data that violate the protocol
ServiceException - if any other service-level failure occurs