org.iids.aos.systemservices.communicator
Class KernelClient

java.lang.Object
  org.iids.aos.systemservices.communicator.KernelClient

All Implemented Interfaces:

AOSapi

public class KernelClient
extends java.lang.Object
implements AOSapi

KernelClient is an AOSapi wrapper class that allows creations of KernelClients, either XML-RPC or SUN-RPC based. This class extends the AOSapi with some extra functions.

Author:

Michel

Nested Class Summary

static class

KernelClient.KernelClientUninitializedException

Nested classes/interfaces inherited from interface org.iids.aos.kernel.AOSapi

AOSapi.AcceptResult, AOSapi.ConnectResult, AOSapi.CreateRoleResult, AOSapi.PrepareWaitACResult, AOSapi.SecSuites, AOSapi.WaitACResult

Field Summary

Fields inherited from interface org.iids.aos.kernel.AOSapi

ACTP_TLS_PROTOCOL_VERSION, MUX_TLS_PROTOCOL_VERSION, SCID_AUTH_ALGO, SCID_AUTH_KEYSIZE, SCID_CERT_SIGN_ALGO, SCID_DIGEST_ALGO, SCID_DIGEST_ALGO_BITLENGTH, SEGMENT_CERT_SUBTYPE, SEGMENT_DIGEST_ALGO, SEGMENT_DIGEST_ALGO_BITLENGTH, SEGMENT_SIGN_SUBTYPE, SEGMENT_TOC_SUBTYPE, SIGN_TOC_ALGO, SIGN_TOC_CERTTYPE, XDR_ENCODING_CHARSET

Constructor Summary

KernelClient(Cookie cookie)

KernelClient(Cookie cookie, KernelConfigParser.KernelConfigParseResult config)
Creates a kernel client using a dedicated config file.

KernelClient(KernelImpl ki)

Method Summary

AOSapi.AcceptResult	accept(Cookie cookie, int listenPort, boolean blocking) Returns the next permitted connection waiting at a listen endpoint.
void	close()
void	closeConnection(Cookie cookie, int connectionID) Closes a connection.
void	closeListenEndpoint(Cookie cookie, int listenPort) Destroys a listen endpoint and closes any pending connections that have arrived at the listen endpoint.
AOSapi.ConnectResult	connect(Cookie cookie, Endpoint listenEndpoint, java.lang.String[] secSuites) Establishes a connection by connecting to a remote listen endpoint.
int	createAgentContainer(Cookie cookie) Creates an empty agent container.
Endpoint	createListenEndpoint(Cookie cookie, int listenPort, java.lang.String[] secSuites) Creates a listen endpoint.
AOSapi.CreateRoleResult	createRole(Cookie cookie, RoleBitmap bitmap) Creates a new role.
int	createSegment(Cookie cookie, int acid, int segmentType, byte[] subtype, byte[] description) Creates a new empty segment and TOC entry in the given agent container, using the given parameters.
void	deleteAgentContainer(Cookie cookie, int acid) Deletes an agent container.
void	deleteRole(Cookie cookie, Cookie childCookie) Deletes an existing role and all kernel resources owned by that role (Agent containers, connection ports, listen ports, other roles etc.)
void	deleteSegment(Cookie cookie, int acid, int segID) Removes the given segment from the given agent container.
void	finalizeAgentContainer(Cookie cookie, int acid) Finalizes an agent container: (a) computes checksums of the container's segments and signs the container using the AOS kernel's private key, and (b) writes the TOC, signature and AOS kernel's key certificate to the agent container's finalization segments.
static KernelClient	getLocalKernelClient() Get an immediate reference to the kernel using KernelClient, instead of one using XML/Sun rpc based clients.
static int	getMaxMsgSize()
int	getParam(Cookie cookie, java.lang.String parameterName) Returns the value of an AOS parameter, a positive integer
void	makePersistent(Cookie cookie, int acid, int segID) Marks the given segment of the given agent container as persistent.
byte[]	peek(Cookie cookie, int connectionID, int max, boolean blocking) As receive() but leaves the data that was read in the connection.
AOSapi.PrepareWaitACResult	prepareWaitAgentContainer(Cookie cookie, java.lang.String[] secSuites) Prepares an incoming agent container shipment.
byte[]	readSegment(Cookie cookie, int acid, int segID, int offset, int length) Read the contents of a segment in the kernel.
TOCEntry[]	readTOC(Cookie cookie, int acid, int offset, int n) Read the TOC from a container in the kernel.
byte[]	receive(Cookie cookie, int connectionID, int max, boolean blocking) Reads available data from a connection up to a specified maximum.
byte[]	receiveExactly(Cookie cookie, int connectionID, int msgLength) Receive an exact amount of data from the connection specified.
byte[]	receiveMessage(Cookie cookie, int connectionID) Receive a Message, which is simply an array of bytes, and which should have been sent on the other side by sendMessage() or sendMessages().
java.util.List<byte[]>	receiveMessages(Cookie cookie, int connectionID) Receive Messages, each of which is simply an array of bytes, and which should have been sent on the other side by sendMessage() or sendMessages().
void	reenableRole(Cookie cookie) Used to reset the role so that it can be used again.
SelectSets	select(Cookie cookie, SelectSets sets, boolean block) Cf.
int	send(Cookie cookie, int connectionID, byte[] buffer) Writes data to a connection.
int	sendExactly(Cookie cookie, int connectionID, byte[] buf) Send an exact amount of data over the connection specified.
int	sendMessage(Cookie cookie, int connectionID, byte[] buf) Send a Message, which is simply an array of bytes, and which can be received on the other side by using receiveMessage().
int	sendMessages(Cookie cookie, int connectionID, java.util.Collection<byte[]> msgs) Send multiple Messages, each of which is simply an array of bytes, and which can be received on the other side by using receiveMessage().
static void	setConfig(KernelConfigParser.KernelConfigParseResult kconfig) Set the default config file to be used.
void	shipAgentContainer(Cookie cookie, int acid, Endpoint dest, java.lang.String[] secSuites, TransactionID tid) Ships a finalized agent container to a remote AOS kernel.
AOSapi.WaitACResult	waitAgentContainer(Cookie cookie, TransactionID[] tids, int blockTime) Waits for completion of an incoming agent container shipment with any of the given transaction ID.
int	writeSegment(Cookie cookie, int acid, int segID, int offset, byte[] frombuf) Write the contents into a segment in the kernel.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

KernelClient

public KernelClient(KernelImpl ki)

KernelClient

public KernelClient(Cookie cookie)
             throws CommunicatorException,
                    KernelClient.KernelClientUninitializedException

Throws:

CommunicatorException

KernelClient.KernelClientUninitializedException

KernelClient

public KernelClient(Cookie cookie,
                    KernelConfigParser.KernelConfigParseResult config)
             throws CommunicatorException,
                    KernelClient.KernelClientUninitializedException

Creates a kernel client using a dedicated config file.

I don't know why the scheme with the static config was used (probably because the config could not be used everywhere). For this we should probably add another method?

Throws:

CommunicatorException

KernelClient.KernelClientUninitializedException

Method Detail

getLocalKernelClient

public static KernelClient getLocalKernelClient()

Get an immediate reference to the kernel using KernelClient, instead of one using XML/Sun rpc based clients. These others require a cookie in the constructor, but the local kernel client does not (it is only used for getParam()).

Returns:

setConfig

public static void setConfig(KernelConfigParser.KernelConfigParseResult kconfig)

Set the default config file to be used. Clients can then create a KernelClient with only a cookie, whereas otherwise they would also need a KernelConfigParseResult. Any further calls to KernelClient(Cookie) will use this default config. Clients requiring an alternate configuration can still use this by using KernelClient(Cookie, KernelConfigParser.KernelConfigParseResult).

close

public void close()

getMaxMsgSize

public static int getMaxMsgSize()

createRole

public AOSapi.CreateRoleResult createRole(Cookie cookie,
                                          RoleBitmap bitmap)
                                   throws KernelException

Description copied from interface: AOSapi

Creates a new role.

Specified by:

createRole in interface AOSapi

Parameters:

cookie - caller cookie

bitmap - the role bitmap for the new role

Returns:

a CreateRoleResult

Throws:

UnknownRoleException - if the caller is unknown

KernelException

deleteRole

public void deleteRole(Cookie cookie,
                       Cookie childCookie)
                throws KernelException

Description copied from interface: AOSapi

Deletes an existing role and all kernel resources owned by that role (Agent containers, connection ports, listen ports, other roles etc.)

Specified by:

deleteRole in interface AOSapi

Parameters:

cookie - caller cookie, must correspond to the parent role that created this role

childCookie - cookie of the role to be deleted

Throws:

KernelException

createAgentContainer

public int createAgentContainer(Cookie cookie)
                         throws KernelException

Description copied from interface: AOSapi

Creates an empty agent container.

Specified by:

createAgentContainer in interface AOSapi

Parameters:

cookie - caller cookie

Returns:

the agent container ID

Throws:

KernelException

deleteAgentContainer

public void deleteAgentContainer(Cookie cookie,
                                 int acid)
                          throws KernelException

Description copied from interface: AOSapi

Deletes an agent container.

Specified by:

deleteAgentContainer in interface AOSapi

Parameters:

cookie - caller cookie

acid - agent container to delete

Throws:

KernelException

createSegment

public int createSegment(Cookie cookie,
                         int acid,
                         int segmentType,
                         byte[] subtype,
                         byte[] description)
                  throws KernelException

Description copied from interface: AOSapi

Creates a new empty segment and TOC entry in the given agent container, using the given parameters. The created segment is marked transient.

Specified by:

createSegment in interface AOSapi

Parameters:

cookie - caller cookie

acid - agent container to create a segment in

segmentType - see XDR documentation of TOC_ENTRY

subtype - see XDR documentation of TOC_ENTRY

description - see XDR documentation of TOC_ENTRY

Returns:

the segment ID

Throws:

KernelException

deleteSegment

public void deleteSegment(Cookie cookie,
                          int acid,
                          int segID)
                   throws KernelException

Description copied from interface: AOSapi

Removes the given segment from the given agent container.

Specified by:

deleteSegment in interface AOSapi

Parameters:

cookie - caller cookie

acid - agent container to delete segment from

segID - segment to delete

Throws:

KernelException

readTOC

public TOCEntry[] readTOC(Cookie cookie,
                          int acid,
                          int offset,
                          int n)
                   throws KernelException

Read the TOC from a container in the kernel. Use a while-loop to read n entries of the TOC of the container, because the kernel is allowed to return data in multiple calls.

Specified by:

readTOC in interface AOSapi

Parameters:

cookie - cookie used to communicate with the kernel

acid - agentcontainer ID

offset - offset within TOC of segment

n - number of TOC-entries to read

Returns:

the TOC entries read (possibly empty)

Throws:

KernelException - if something went wrong while reading the TOC

readSegment

public byte[] readSegment(Cookie cookie,
                          int acid,
                          int segID,
                          int offset,
                          int length)
                   throws KernelException

Read the contents of a segment in the kernel. Use a while-loop to read the length bytes of the contents of the segment, because the kernel is allowed to return data in multiple calls.

Specified by:

readSegment in interface AOSapi

Parameters:

cookie - cookie used to communicate with the kernel

acid - agentcontainer ID

segID - segment ID

offset - offset within segment ID

length - number of bytes to read

Returns:

the bytes that were read (possibly empty)

Throws:

KernelException - if something went wrong while reading segments

writeSegment

public int writeSegment(Cookie cookie,
                        int acid,
                        int segID,
                        int offset,
                        byte[] frombuf)
                 throws KernelException

Write the contents into a segment in the kernel. Use a while-loop to write the entire contents of the buffer, because the kernel is allowed not to write all data.

Specified by:

writeSegment in interface AOSapi

Parameters:

cookie - cookie used to communicate with the kernel

acid - agentcontainer ID

segID - segment ID

offset - offset within segment to write data

frombuf - buffer containing data to write

Returns:

the number of bytes that were written

Throws:

KernelException - if something went wrong while writing segments

makePersistent

public void makePersistent(Cookie cookie,
                           int acid,
                           int segID)
                    throws KernelException

Description copied from interface: AOSapi

Marks the given segment of the given agent container as persistent. Henceforth the segment cannot be deleted, modified, or made transient.

Specified by:

makePersistent in interface AOSapi

Parameters:

cookie - caller cookie

acid - agent container whose segment to make persistent

segID - segment to make persistent

Throws:

KernelException

finalizeAgentContainer

public void finalizeAgentContainer(Cookie cookie,
                                   int acid)
                            throws KernelException

Description copied from interface: AOSapi

Finalizes an agent container: (a) computes checksums of the container's segments and signs the container using the AOS kernel's private key, and (b) writes the TOC, signature and AOS kernel's key certificate to the agent container's finalization segments.

Specified by:

finalizeAgentContainer in interface AOSapi

Parameters:

cookie - caller cookie

acid - agent container to finalize

Throws:

KernelException

shipAgentContainer

public void shipAgentContainer(Cookie cookie,
                               int acid,
                               Endpoint dest,
                               java.lang.String[] secSuites,
                               TransactionID tid)
                        throws KernelException

Description copied from interface: AOSapi

Ships a finalized agent container to a remote AOS kernel.

Specified by:

shipAgentContainer in interface AOSapi

Parameters:

cookie - caller cookie

acid - agent container to ship

dest - the listen endpoint that the remote kernel uses for incoming agent container shipments (note: dest.port currently unused)

secSuites - a series of cipher suites acceptable to the caller, null or empty is equivalent to ALL_SEC_SUITES, as ACTP requires authentication.

tid - the transaction ID for this shipment, created by the remote AOS kernel

Throws:

KernelException

prepareWaitAgentContainer

public AOSapi.PrepareWaitACResult prepareWaitAgentContainer(Cookie cookie,
                                                            java.lang.String[] secSuites)
                                                     throws KernelException

Description copied from interface: AOSapi

Prepares an incoming agent container shipment. A transaction ID for this shipment is allocated and returned to the caller, together with this AOS kernel's virtual listen endpoint for incoming shipments. The caller should pass this information to its peer on the remote AOS kernel so that the peer may ship the agent container. The caller may then wait for completion of the shipment by calling waitAgentContainer().

Specified by:

prepareWaitAgentContainer in interface AOSapi

Parameters:

cookie - caller cookie

secSuites - a series of cipher suites acceptable to the caller, null or empty is equivalent to ALL_SEC_SUITES, as ACTP requires authentication.

Returns:

a transactionID and a listenEndpoint

Throws:

KernelException

waitAgentContainer

public AOSapi.WaitACResult waitAgentContainer(Cookie cookie,
                                              TransactionID[] tids,
                                              int blockTime)

Description copied from interface: AOSapi

Waits for completion of an incoming agent container shipment with any of the given transaction ID.

Specified by:

waitAgentContainer in interface AOSapi

Parameters:

cookie - caller cookie

tids - TransactionIDs for the AC shipment. All exceptions occuring will include the tid of the transaction that met the error.

blockTime - time in seconds in which the kernel will wait for an ACT to be initiated. blockTime 0 means ``poll''.

Returns:

the agent container ID of the incoming agent container, the tid and the source kernel, if the shipment was successful. The following exceptions can occur. Note, these exceptions are not thrown, but are encoded in the return value. # exception UnknownRoleException if the caller is unknown exception MethodNotAllowedException if the caller is not allowed to invoke the primitive exception ACTPACTooLargeException if the AC exceeds the remote kernel's internal limit exception ACTPACFormatException if the AC received did not meet the format exception ACTPACVerifyException if the AC received was not correctly signed exception InputOutputException if the kernel encountered persistent problems while receiving the AC exception TransientIOException if the kernel encountered transient problems while receiving the AC exception LimitExceededException if the caller exceeded an AOS resource limit exception KernelResetException if the kernel has been restarted exception IPCException if the operation failed due to an IPC error

createListenEndpoint

public Endpoint createListenEndpoint(Cookie cookie,
                                     int listenPort,
                                     java.lang.String[] secSuites)
                              throws KernelException

Description copied from interface: AOSapi

Creates a listen endpoint. The listen port number can either be specified (explicit allocation) or left unspecified, in which case the AOS kernel will pick an unused listen port number. The caller may pass a series of cipher suites that it finds acceptable. This listen endpoint will only permit connections that use one of the specified cipher suites. If the caller does not pass a cipher suite, the listen endpoint will permit unsecure connections as well as connections that use any cipher suite supported by this AOS kernel. Note: other attributes of the listen endpoint, such as the number of outstanding connection requests that may be pending ('backlog'), are determined by the AOS kernel.

Specified by:

createListenEndpoint in interface AOSapi

Parameters:

cookie - caller cookie

listenPort - the listen port number to use, or 0 to let the AOS kernel pick one

secSuites - a series of cipher suites acceptable to the caller, or null or empty to leave unspecified. Kernel will then selected appropriate suites.

Returns:

the address of the listen endpoint created. The listen port number that identifies the listen endpoint is part of the address. The scid field of the address will be set iff this AOS kernel supports authentication

Throws:

KernelException

closeListenEndpoint

public void closeListenEndpoint(Cookie cookie,
                                int listenPort)
                         throws KernelException

Description copied from interface: AOSapi

Destroys a listen endpoint and closes any pending connections that have arrived at the listen endpoint.

Specified by:

closeListenEndpoint in interface AOSapi

Parameters:

cookie - caller cookie

listenPort - the listen port number

Throws:

KernelException

accept

public AOSapi.AcceptResult accept(Cookie cookie,
                                  int listenPort,
                                  boolean blocking)
                           throws KernelException

Description copied from interface: AOSapi

Returns the next permitted connection waiting at a listen endpoint. If blocking, first waits until such a connection becomes available. Note that this call will only return connections that are permitted according to the secSuites specification of createListenEndpoint().

Specified by:

accept in interface AOSapi

Parameters:

cookie - caller cookie

listenPort - the listen port number

blocking - whether to allow this method to block

Returns:

the connection info or null if ! blocking and no permitted connection was available

Throws:

KernelException

connect

public AOSapi.ConnectResult connect(Cookie cookie,
                                    Endpoint listenEndpoint,
                                    java.lang.String[] secSuites)
                             throws KernelException

Description copied from interface: AOSapi

Establishes a connection by connecting to a remote listen endpoint. If the scid field of the listen endpoint address is set, then the remote AOS kernel must be authenticated in order for the connection establishment to succeed. The caller may pass a series of cipher suites that it finds acceptable for this connection, in which case the connection may only use one of the provided cipher suites. If the caller does not pass a cipher suite, the connection may be unsecure or may use any cipher suite supported by this AOS kernel.

Specified by:

connect in interface AOSapi

Parameters:

cookie - caller cookie

listenEndpoint - the address of the remote listen endpoint

secSuites - a series of cipher suites acceptable to the caller, or null or empty to leave unspecified

Returns:

the connection info

Throws:

KernelException

closeConnection

public void closeConnection(Cookie cookie,
                            int connectionID)
                     throws KernelException

Description copied from interface: AOSapi

Closes a connection. Pending unsent data will still be delivered (barring failures) as long as the remote party does not close as well. send() and receive() calls on the connection are illegal following this call.

Specified by:

closeConnection in interface AOSapi

Parameters:

cookie - caller cookie

connectionID - the connection to close

Throws:

KernelException

send

public int send(Cookie cookie,
                int connectionID,
                byte[] buffer)
         throws KernelException

Description copied from interface: AOSapi

Writes data to a connection.

Specified by:

send in interface AOSapi

Parameters:

cookie - caller cookie

connectionID - the connection to write to

buffer - the buffer that holds the data

Returns:

the number of bytes actually written

Throws:

KernelException

receive

public byte[] receive(Cookie cookie,
                      int connectionID,
                      int max,
                      boolean blocking)
               throws KernelException

Description copied from interface: AOSapi

Reads available data from a connection up to a specified maximum. If 'blocking', first blocks until at least one byte of data is available.

Specified by:

receive in interface AOSapi

Parameters:

cookie - caller cookie

connectionID - the connection to read

max - maximum number of bytes to read

blocking - whether to allow this method to block

Returns:

the bytes read. Non-empty if blocking

Throws:

KernelException

peek

public byte[] peek(Cookie cookie,
                   int connectionID,
                   int max,
                   boolean blocking)
            throws KernelException

Description copied from interface: AOSapi

As receive() but leaves the data that was read in the connection. The data remains available for reading by subsequent invocations to receive() and peek().

Specified by:

peek in interface AOSapi

Throws:

KernelException

select

public SelectSets select(Cookie cookie,
                         SelectSets sets,
                         boolean block)
                  throws KernelException

Description copied from interface: AOSapi

Cf. the UNIX select system call.

Specified by:

select in interface AOSapi

Parameters:

cookie - caller cookie

sets - set of three sets: readSet, writeSet, exceptSet readSet : set of local descriptors to check for data/connection availability writeSet set of local descriptors to check for writability exceptSet set of local descriptors to check for exceptions

block - whether to block or not

Returns:

All the sets will have been modified to reflect active descriptors.

Throws:

KernelException

getParam

public int getParam(Cookie cookie,
                    java.lang.String parameterName)
             throws KernelException

Description copied from interface: AOSapi

Returns the value of an AOS parameter, a positive integer

Specified by:

getParam in interface AOSapi

Parameters:

cookie - caller cookie

parameterName - the name of the AOS parameter

Returns:

the value of the parameter

Throws:

KernelException

reenableRole

public void reenableRole(Cookie cookie)
                  throws KernelException

Description copied from interface: AOSapi

Used to reset the role so that it can be used again. After a crash (or graceful exit where roles are not deleted) of AOS, all roles of AOS are locked and method invocations by a role throw a KernelResetException.

Specified by:

reenableRole in interface AOSapi

Parameters:

cookie - caller cookie

Throws:

KernelException

receiveExactly

public byte[] receiveExactly(Cookie cookie,
                             int connectionID,
                             int msgLength)
                      throws KernelException

Receive an exact amount of data from the connection specified. Keep receiving data until we have received exactly the number of bytes specified in the parameter msgLength.
This method is not MT-safe. Synchronization is necessary when reading concurrently from the same connectionID.

Throws:

KernelException

sendExactly

public int sendExactly(Cookie cookie,
                       int connectionID,
                       byte[] buf)
                throws KernelException

Send an exact amount of data over the connection specified. Keep sending data until we have sent exactly the entire buffer.
This method is not MT-safe. Synchronization is necessary when writing concurrently to the same connectionID.

Throws:

KernelException

sendMessage

public int sendMessage(Cookie cookie,
                       int connectionID,
                       byte[] buf)
                throws KernelException

Send a Message, which is simply an array of bytes, and which can be received on the other side by using receiveMessage().
This method is MT-safe. Synchronization is done when writing concurrently to the same connectionID.

Throws:

KernelException

sendMessages

public int sendMessages(Cookie cookie,
                        int connectionID,
                        java.util.Collection<byte[]> msgs)
                 throws KernelException

Send multiple Messages, each of which is simply an array of bytes, and which can be received on the other side by using receiveMessage().
This method is MT-safe. Synchronization is done when writing concurrently to the same connectionID.

Throws:

KernelException

receiveMessage

public byte[] receiveMessage(Cookie cookie,
                             int connectionID)
                      throws KernelException

Receive a Message, which is simply an array of bytes, and which should have been sent on the other side by sendMessage() or sendMessages().
This method blocks until a message has been read completely, except in case of errors, in which case a KernelException is thrown.
This method is MT-safe. Synchronization is done when reading concurrently from the same connectionID.

Throws:

KernelException

receiveMessages

public java.util.List<byte[]> receiveMessages(Cookie cookie,
                                              int connectionID)
                                       throws KernelException

Receive Messages, each of which is simply an array of bytes, and which should have been sent on the other side by sendMessage() or sendMessages().
This method blocks until a message has been read completely, except in case of errors, in which case a KernelException is thrown.
This method is MT-safe. Synchronization is done when reading concurrently from the same connectionID.

Throws:

KernelException