org.iids.aos.kernel
Interface AOSapi

All Known Implementing Classes:

KernelClient, KernelImpl, SunRpcKernelClient, XmlRpcKernelClient

public interface AOSapi

RPC-neutral specification of the AOS kernel API version 5. All calls are defined to be thread-safe. The interface is assumed to be used also for proxies in Java AppMWs, so all primitives should allow for IPCException-s to indicate communication problems.

Author:

Patrick Verkaik, Arno Bakker

Nested Class Summary

static class	AOSapi.AcceptResult Return value of accept().
static class	AOSapi.ConnectResult Return value of connect().
static class	AOSapi.CreateRoleResult Return value of createRole().
static class	AOSapi.PrepareWaitACResult Return value of prepareWaitAgentContainer().
static class	AOSapi.SecSuites The set of security suites allowed by the spec.
static class	AOSapi.WaitACResult Return value of waitAgentContainer().

Field Summary

static java.lang.String	ACTP_TLS_PROTOCOL_VERSION Java identifier for the secure protocol used for ACTP
static java.lang.String	MUX_TLS_PROTOCOL_VERSION Java identifier for the secure protocol used for mux base connections
static java.lang.String	SCID_AUTH_ALGO Java security algorithm used for authentication and (TOC) signing.
static int	SCID_AUTH_KEYSIZE Size of keys used for authentication
static java.lang.String	SCID_CERT_SIGN_ALGO Java security algorithm used for certificate signing.
static java.lang.String	SCID_DIGEST_ALGO Java message digest algorithm to use to calculate SCID from public key
static int	SCID_DIGEST_ALGO_BITLENGTH Size of the SCID digest in bits
static java.lang.String	SEGMENT_CERT_SUBTYPE
static java.lang.String	SEGMENT_DIGEST_ALGO Java security algorithm used to compute checksum of segment content.
static int	SEGMENT_DIGEST_ALGO_BITLENGTH Size of the segment digest in bits.
static java.lang.String	SEGMENT_SIGN_SUBTYPE
static java.lang.String	SEGMENT_TOC_SUBTYPE Segment subtypes for special segments
static java.lang.String	SIGN_TOC_ALGO Java security algorithm used to sign a serialised TOC.
static java.lang.String	SIGN_TOC_CERTTYPE Certificate type used in finalized TOC
static java.lang.String	XDR_ENCODING_CHARSET Encoding charset to use to encoded Java strings to XDR

Method Summary

AOSapi.AcceptResult	accept(Cookie cookie, int listenPort, boolean blocking) Returns the next permitted connection waiting at a listen endpoint.
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.
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) Reads a number of bytes from the given segment in the given agent container.
TOCEntry[]	readTOC(Cookie cookie, int acid, int offset, int n) Reads n TOC entries of an agent container, starting at the entry for segment ID 'offset'.
byte[]	receive(Cookie cookie, int connectionID, int max, boolean blocking) Reads available data from a connection up to a specified maximum.
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.
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) Writes a number of bytes to the given segment in the given agent container.

Field Detail

SCID_AUTH_ALGO

static final java.lang.String SCID_AUTH_ALGO

Java security algorithm used for authentication and (TOC) signing.

See Also:

Constant Field Values

SCID_AUTH_KEYSIZE

static final int SCID_AUTH_KEYSIZE

Size of keys used for authentication

See Also:

Constant Field Values

SCID_CERT_SIGN_ALGO

static final java.lang.String SCID_CERT_SIGN_ALGO

Java security algorithm used for certificate signing.

See Also:

Constant Field Values

SCID_DIGEST_ALGO

static final java.lang.String SCID_DIGEST_ALGO

Java message digest algorithm to use to calculate SCID from public key

See Also:

Constant Field Values

SCID_DIGEST_ALGO_BITLENGTH

static final int SCID_DIGEST_ALGO_BITLENGTH

Size of the SCID digest in bits

See Also:

Constant Field Values

SEGMENT_DIGEST_ALGO

static final java.lang.String SEGMENT_DIGEST_ALGO

Java security algorithm used to compute checksum of segment content.

See Also:

Constant Field Values

SEGMENT_DIGEST_ALGO_BITLENGTH

static final int SEGMENT_DIGEST_ALGO_BITLENGTH

Size of the segment digest in bits.

See Also:

Constant Field Values

XDR_ENCODING_CHARSET

static final java.lang.String XDR_ENCODING_CHARSET

Encoding charset to use to encoded Java strings to XDR

See Also:

Constant Field Values

SEGMENT_TOC_SUBTYPE

static final java.lang.String SEGMENT_TOC_SUBTYPE

Segment subtypes for special segments

See Also:

Constant Field Values

SEGMENT_CERT_SUBTYPE

static final java.lang.String SEGMENT_CERT_SUBTYPE

See Also:

Constant Field Values

SEGMENT_SIGN_SUBTYPE

static final java.lang.String SEGMENT_SIGN_SUBTYPE

See Also:

Constant Field Values

SIGN_TOC_ALGO

static final java.lang.String SIGN_TOC_ALGO

Java security algorithm used to sign a serialised TOC.

See Also:

Constant Field Values

SIGN_TOC_CERTTYPE

static final java.lang.String SIGN_TOC_CERTTYPE

Certificate type used in finalized TOC

See Also:

Constant Field Values

MUX_TLS_PROTOCOL_VERSION

static final java.lang.String MUX_TLS_PROTOCOL_VERSION

Java identifier for the secure protocol used for mux base connections

See Also:

Constant Field Values

ACTP_TLS_PROTOCOL_VERSION

static final java.lang.String ACTP_TLS_PROTOCOL_VERSION

Java identifier for the secure protocol used for ACTP

See Also:

Constant Field Values

Method Detail

createRole

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

Creates a new role.

Parameters:

cookie - caller cookie

bitmap - the role bitmap for the new role

Returns:

a CreateRoleResult

Throws:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

BadArgumentException - if the bitmap is not a strict subset of the caller's role's bitmap

RandomSourceException - if the kernel could not generate a new cookie

LimitExceededException - if the caller exceeded an AOS resource limit

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

deleteRole

void deleteRole(Cookie cookie,
                Cookie childCookie)
                throws KernelException

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

Parameters:

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

childCookie - cookie of the role to be deleted

Throws:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

AccessDeniedException - if the caller does not own the kernel resource.

UnknownRoleIDException - if the childCookie is unknown.

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

createAgentContainer

int createAgentContainer(Cookie cookie)
                         throws KernelException

Creates an empty agent container.

Parameters:

cookie - caller cookie

Returns:

the agent container ID

Throws:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

LimitExceededException - if the caller exceeded an AOS resource limit

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

deleteAgentContainer

void deleteAgentContainer(Cookie cookie,
                          int acid)
                          throws KernelException

Deletes an agent container.

Parameters:

cookie - caller cookie

acid - agent container to delete

Throws:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

AccessDeniedException - if the caller does not own the kernel resource.

UnknownACIDException - if the agent container ID does not exist

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

createSegment

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

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

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:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

AccessDeniedException - if the caller does not own the kernel resource.

UnknownACIDException - if the agent container ID does not exist

BadArgumentException - if segmentType is invalid (or one of the special segment types), or subtype or description has the wrong number of bytes

LimitExceededException - if the caller exceeded an AOS resource limit

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

deleteSegment

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

Removes the given segment from the given agent container.

Parameters:

cookie - caller cookie

acid - agent container to delete segment from

segID - segment to delete

Throws:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

AccessDeniedException - if the caller does not own the kernel resource.

UnknownACIDException - if the agent container ID does not exist

UnknownSegmentIDException - if the segment ID does not exist

PersistentSegmentException - if an attempt is made to delete a persistent segment

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

readTOC

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

Reads n TOC entries of an agent container, starting at the entry for segment ID 'offset'. May return fewer than n entries iff fewer than n are available from that offset. Also note that the sequence of segment IDs in the agent container may contain gaps. Therefore, the segment IDs of returned entries may exceed 'n+offset-1'. The finalization TOC entries (see XDR specification) are available only if finalizeAgentContainer() has been called at some point. The migration TOC entries (see XDR specification) are available only if the agent container was originally shipped from another AOS kernel.

Parameters:

cookie - caller cookie

acid - agent container to read TOC from

offset - segment ID of first entry requested

n - the number of entries requested

Returns:

the TOC entries read (possibly empty)

Throws:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

AccessDeniedException - if the caller does not own the kernel resource.

UnknownACIDException - if the agent container ID does not exist

BadArgumentException - if offset or n was invalid

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

readSegment

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

Reads a number of bytes from the given segment in the given agent container. If length > 0 and data is available at offset, then reads at least one byte and at most length bytes starting at offset. If length == 0 or no data is available at offset (e.g. offset >= segment size), then zero bytes are read. Fewer bytes than were requested may be read even if more data is available. The only way the caller can tell from the results of readSegment() that the end of a segment has been reached is to request at least one byte and be returned zero bytes.

Parameters:

cookie - caller cookie

acid - agent container to read from

segID - segment to read from

offset - offset in segment to start reading at

length - number of bytes requested

Returns:

the bytes that were read (possibly empty)

Throws:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

AccessDeniedException - if the caller does not own the kernel resource.

UnknownACIDException - if the agent container ID does not exist

UnknownSegmentIDException - if the segment ID does not exist

BadArgumentException - if the offset or length is invalid

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

writeSegment

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

Writes a number of bytes to the given segment in the given agent container. If frombuf.length > 0, then writes at least one byte and at most frombuf.length bytes starting at offset. Otherwise does nothing. Fewer bytes may be written than were requested even if more data can be written in a subsequent call.

Parameters:

cookie - caller cookie

acid - agent container to write to

segID - segment to write to

offset - offset in segment to start writing at

frombuf - buffer containing the bytes to write

Returns:

the number of bytes that were written

Throws:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

AccessDeniedException - if the caller does not own the kernel resource.

UnknownACIDException - if the agent container ID does not exist

UnknownSegmentIDException - if the segment ID does not exist

SegmentHoleException - if offset is further than one byte beyond the end of the segment

PersistentSegmentException - if an attempt is made to write to a persistent segment

BadArgumentException - if the offset is invalid

LimitExceededException - if the caller exceeded an AOS resource limit

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

makePersistent

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

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

Parameters:

cookie - caller cookie

acid - agent container whose segment to make persistent

segID - segment to make persistent

Throws:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

AccessDeniedException - if the caller does not own the kernel resource.

UnknownACIDException - if the agent container ID does not exist

UnknownSegmentIDException - if the segment ID does not exist

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

finalizeAgentContainer

void finalizeAgentContainer(Cookie cookie,
                            int acid)
                            throws KernelException

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.

Parameters:

cookie - caller cookie

acid - agent container to finalize

Throws:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

AccessDeniedException - if the caller does not own the kernel resource.

UnknownACIDException - if the agent container ID does not exist

LimitExceededException - if the caller exceeded an AOS resource limit

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

shipAgentContainer

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

Ships a finalized agent container to a remote AOS kernel.

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:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

AccessDeniedException - if the caller does not own the kernel resource.

UnknownACIDException - if the agent container ID does not exist

ACNotFinalizedException - if the agent container has not yet been finalized

ConnectionSetupException - if the kernel has insufficient resources to setup a new base connection

AuthenticationException - if the remote kernel could not be authenticated

TargetUnknownException - if the remote AOS kernel did not recognise transactionID or endpoint index

ACTPACTooLargeException - if the AC exceeds the remote kernel's internal limit

ACTPPeerTransientException - if the remote kernel encounters a transient error during ACTP.

ACTPPeerInternalException - if the remote kernel encounters a serious, persistent error during ACTP.

ACTPReceiptException - if the remote AOS kernel did not return a proper receipt for the AC

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

prepareWaitAgentContainer

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

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().

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:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

RandomSourceException - if the kernel could not generate a unique XID

NoKnownSecuritySuiteException - if none of the cipher suites in secSuites are supported by this kernel

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

waitAgentContainer

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.

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

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

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.

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:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

BadArgumentException - e.g. if an attempt is made to explicitly allocate a listen port number that is already in use

NoKnownSecuritySuiteException - if a cipher suite in secSuites is not supported by this AOS kernel

InputOutputException - if the kernel encountered persistent communication problems

TransientIOException - if the kernel encountered transient communication problems

LimitExceededException - if the caller exceeded an AOS resource limit

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

closeListenEndpoint

void closeListenEndpoint(Cookie cookie,
                         int listenPort)
                         throws KernelException

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

Parameters:

cookie - caller cookie

listenPort - the listen port number

Throws:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

AccessDeniedException - if the caller does not own the kernel resource.

InputOutputException - if the kernel encountered persistent communication problems

TransientIOException - if the kernel encountered transient communication problems

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

accept

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

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().

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:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

AccessDeniedException - if the caller does not own the kernel resource.

UnknownEndpointDescrException - if the listenPort is no known

InputOutputException - if the kernel encountered persistent communication problems

TransientIOException - if the kernel encountered transient communication problems

LimitExceededException - if the caller exceeded an AOS resource limit

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

connect

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

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.

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:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

NoKnownSecuritySuiteException - if none of the cipher suites in secSuites are supported by this kernel

ConnectionSetupException - if the kernel has insufficient resources to setup a new base connection

PeerUnreachableException - if the peer could not be physically reached over the network

SecuritySuiteAgreementException - if the local AOS kernel and the remote AOS kernel were unable to negotiate security parameters required for establishing the connection

AuthenticationException - if the remote kernel could not be authenticated

TargetUnknownException - if the remote AOS kernel did not recognise the endpoint index

InputOutputException - if the kernel encountered persistent communication problems

TransientIOException - if the kernel encountered transient communication problems

LimitExceededException - if the caller exceeded an AOS resource limit

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

closeConnection

void closeConnection(Cookie cookie,
                     int connectionID)
                     throws KernelException

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.

Parameters:

cookie - caller cookie

connectionID - the connection to close

Throws:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

AccessDeniedException - if the caller does not own the kernel resource.

UnknownConnectionIDException - if the connection ID is unknown

InputOutputException - if the kernel encountered persistent communication problems

TransientIOException - if the kernel encountered transient communication problems

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

send

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

Writes data to a connection.

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:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

AccessDeniedException - if the caller does not own the kernel resource.

UnknownConnectionIDException - if the connection ID is unknown

TargetUnknownException - if the connection was closed because the peer's role was deleted

PeerClosedConnectionException - if the peer gracefully closed the connection

InputOutputException - if the kernel encountered persistent communication problems

TransientIOException - if the kernel encountered transient communication problems

LimitExceededException - if the caller exceeded an AOS resource limit

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

receive

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

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

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:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

AccessDeniedException - if the caller does not own the kernel resource.

UnknownConnectionIDException - if the connection ID is unknown

BadArgumentException - if 'max' is zero

PeerClosedConnectionException - if the peer gracefully closed the connection

InputOutputException - if the kernel encountered persistent communication problems

TransientIOException - if the kernel encountered transient communication problems

LimitExceededException - if the caller exceeded an AOS resource limit

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

peek

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

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().

Throws:

KernelException

select

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

Cf. the UNIX select system call.

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:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

getParam

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

Returns the value of an AOS parameter, a positive integer

Parameters:

cookie - caller cookie

parameterName - the name of the AOS parameter

Returns:

the value of the parameter

Throws:

UnknownRoleException - if the caller is unknown

MethodNotAllowedException - if the caller is not allowed to invoke the primitive

KernelResetException - if the kernel has been restarted

IPCException - if the operation failed due to an IPC error

KernelException

reenableRole

void reenableRole(Cookie cookie)
                  throws KernelException

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.

Parameters:

cookie - caller cookie

Throws:

UnknownRoleException - if the caller is unknown

IPCException - if the operation failed due to an IPC error

KernelException