com.buildforge.services.common.api
Class AbstractProtocolImpl

java.lang.Object
  extended by com.buildforge.services.common.api.AbstractProtocolImpl

public abstract class AbstractProtocolImpl
extends java.lang.Object

Utility class that defines the basic interaction between the APIConnection class and protocol implementations. In general, a protocol implementation may access the read/write buffers of the connection directly, but it will generally be preferable to operate in terms of the read and write methods provided by this class.


Field Summary
static java.lang.Class<AbstractProtocolImpl> CLASS
          Local reference to the class object to avoid the use of ".class".
static java.util.logging.Logger log
          Logger
 
Method Summary
 void check()
          Verifies that the connection is still valid.
abstract  Protocol getProtocol()
          Returns the protocol that this implements.
 void invalidate()
          Invalidates this connection, such that any future requests will instantly throw an IOException.
 void invalidate(ServiceException se)
          Invalidates this connection, such that any future requests will instantly throw an IOException.
abstract  APIRequest readRequest(boolean isServer)
          Runs the request decoder.
abstract  void writeEntry(java.lang.String key)
          Write a data entry with a null value to the current API request.
abstract  void writeEntry(java.lang.String key, java.util.BitSet obj)
          Write a data entry that s a bit set to the current API request.
abstract  void writeEntry(java.lang.String key, boolean value)
          Write a data entry that is a char to the current API request.
abstract  void writeEntry(java.lang.String key, char value)
          Write a data entry that is a char to the current API request.
abstract  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.
abstract  void writeEntry(java.lang.String key, double value)
          Write a data entry that is a double to the current API request.
abstract  void writeEntry(java.lang.String key, java.lang.Enum<?> value)
          Write a data entry that is an enumerated type to the current API request.
abstract  void writeEntry(java.lang.String key, int value)
          Write a data entry that is an int to the current API request.
abstract  void writeEntry(java.lang.String key, long value)
          Write a data entry that is a long to the current API request.
abstract  void writeEntry(java.lang.String key, java.util.Map<?,?> value)
          Write a data entry that is a map to the current API request.
abstract  void writeEntry(java.lang.String key, java.lang.Number value)
          Write a data entry that is a number object to the current API request.
abstract  void writeEntry(java.lang.String key, java.lang.Object obj)
          Write a data entry of unknown type to the current API request.
abstract  void writeEntry(java.lang.String key, java.lang.Object[] value)
          Write a data entry that is an array to the current API request.
abstract  void writeEntry(java.lang.String key, java.lang.String value)
          Write a data entry that is a string to the current API request.
abstract  void writeFooter()
          Completes an active response, including flushing it.
abstract  void writeHeader(int cmd, int as)
          Begins an active response.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CLASS

public static final java.lang.Class<AbstractProtocolImpl> CLASS
Local reference to the class object to avoid the use of ".class".


log

public static final java.util.logging.Logger log
Logger

Method Detail

getProtocol

public abstract Protocol getProtocol()
Returns the protocol that this implements.

Returns:
the protocol (this should never null)

invalidate

public void invalidate()
Invalidates this connection, such that any future requests will instantly throw an IOException.


invalidate

public void invalidate(ServiceException se)
Invalidates this connection, such that any future requests will instantly throw an IOException.


check

public void check()
           throws java.io.IOException
Verifies that the connection is still valid. If it is not, then an IOException is thrown.

Throws:
java.io.IOException - if the connection is no longer valid.

writeHeader

public abstract void writeHeader(int cmd,
                                 int as)
                          throws java.io.IOException
Begins an active response.

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

writeFooter

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

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

writeEntry

public abstract void writeEntry(java.lang.String key)
                         throws java.io.IOException
Write a data entry with a null value to the current API request.

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

writeEntry

public abstract 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 abstract void writeEntry(java.lang.String key,
                                java.util.BitSet obj)
                         throws java.io.IOException
Write a data entry that s a bit set to the current API request. The bit set should be written as a string that contains the entire bit set as a hex string.

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 abstract 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 abstract 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 abstract 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 abstract 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 abstract 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 abstract 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 abstract 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 abstract 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 abstract 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 abstract 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 abstract 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 final 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. The object is serialized to an array, and written as such.

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 abstract 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