org.iids.aos.kernel.ac
Class AgentContainer

java.lang.Object
  org.iids.aos.kernel.ac.AgentContainer

All Implemented Interfaces:

KernelResource

public class AgentContainer
extends java.lang.Object
implements KernelResource

Defines the agent container and takes care of its on-disk representation and provides synchronisation for all items contained in an agent container.

Author:

Patrick Verkaik

Field Summary

static java.lang.String	FINALIZED_FILENAME
static java.lang.String	OWNER_FILENAME
static int	SEGMENT_ID_MAX_SPECIAL
static int	SEGMENT_ID_MIN_SPECIAL

Constructor Summary

AgentContainer(int acid, java.io.File agentContainersDir)
Creates an agent container object for a new agent container object.

Method Summary

static void	checkFinalized(java.io.File acFile, java.lang.String expectedSCID, boolean verifyChecksum) Check a finalized AC received from a remote kernel.
void	checkOwnerIs(Role r) Check if the owner is the expected owner
void	checkReceipt(java.security.Signature sig, byte[] sigBytes)
void	createFromFile(java.io.File acFile, boolean verifyChecksums) Create an agentcontainer from a file containing a finalized AC received from a remote kernel
int	createSegment(int segmentType, byte[] subtype, byte[] description)
void	delete() Deletes this agent container's state.
void	deleteSegment(int segmentID) The semantics follow AOSapi.deleteSegment().
void	finalizeAgentContainer(boolean sign, java.security.PrivateKey privateKey, byte[] certificate) The semantics follow AOSapi.finalizeAgentContainer().
int	getACID() Returns this agent container's agent container ID.
java.io.File	getFinalizedFile() Used by JUnit and Arno
long	getFinalizedLength() Returns the length of the finalized agent container last finalized by finalizeAgentContainer(), or -1 if finalizeAgentContainer() has not yet been called.
Role	getOwner()
SegmentInfo	getSegmentInfo(int segID) Requests the TOC entry for segment 'segID'.
boolean	isFinalized()
void	makePersistent(int segmentID) The semantics follow AOSapi.makePersistent().
void	marshalFinalizedState(java.io.OutputStream outs, int startOffset, int endOffset) Writes the agent container last finalized by finalizeAgentContainer() to a virtual connection.
byte[]	readSegment(int segmentID, int offset, int length) The semantics follow AOSapi.readSegment().
TOCEntry[]	readTOC(int offset, int n) The semantics follow AOSapi.readTOC().
TOC_ENTRY[]	readXDRTOC(int offset, int n)
void	setOwner(Role r)
int	tocSize() Returns the number of TOC entries in this agent container.
int	writeSegment(int segmentID, int offset, int length, byte[] bytes) The semantics follow AOSapi.writeSegment().
int	writeSegment(int segmentID, int offset, int length, byte[] bytes, boolean sync) With sync capability

Methods inherited from class java.lang.Object

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

Field Detail

SEGMENT_ID_MIN_SPECIAL

public static final int SEGMENT_ID_MIN_SPECIAL

See Also:

Constant Field Values

SEGMENT_ID_MAX_SPECIAL

public static final int SEGMENT_ID_MAX_SPECIAL

See Also:

Constant Field Values

FINALIZED_FILENAME

public static final java.lang.String FINALIZED_FILENAME

See Also:

Constant Field Values

OWNER_FILENAME

public static final java.lang.String OWNER_FILENAME

See Also:

Constant Field Values

Constructor Detail

AgentContainer

public AgentContainer(int acid,
                      java.io.File agentContainersDir)
               throws InputOutputException

Creates an agent container object for a new agent container object.

Parameters:

acid - agent container ID of this object

agentContainersDir - the directory in which agent containers are stored

Throws:

InputOutputException

Method Detail

getACID

public int getACID()

Returns this agent container's agent container ID.

delete

public void delete()
            throws InputOutputException

Deletes this agent container's state. The agent container object cannot be used following this call.

Throws:

InputOutputException

createSegment

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

Throws:

KernelException

deleteSegment

public void deleteSegment(int segmentID)
                   throws UnknownSegmentIDException,
                          PersistentSegmentException,
                          InputOutputException,
                          AccessDeniedException

The semantics follow AOSapi.deleteSegment().

Throws:

UnknownSegmentIDException

PersistentSegmentException

InputOutputException

AccessDeniedException

tocSize

public int tocSize()

Returns the number of TOC entries in this agent container.

getSegmentInfo

public SegmentInfo getSegmentInfo(int segID)

Requests the TOC entry for segment 'segID'.

Returns:

the requested TOC entry or null if non-existent

readXDRTOC

public TOC_ENTRY[] readXDRTOC(int offset,
                              int n)

readTOC

public TOCEntry[] readTOC(int offset,
                          int n)

The semantics follow AOSapi.readTOC().

readSegment

public byte[] readSegment(int segmentID,
                          int offset,
                          int length)
                   throws KernelException

The semantics follow AOSapi.readSegment().

Throws:

KernelException

writeSegment

public int writeSegment(int segmentID,
                        int offset,
                        int length,
                        byte[] bytes)
                 throws KernelException

The semantics follow AOSapi.writeSegment().

Throws:

KernelException

writeSegment

public int writeSegment(int segmentID,
                        int offset,
                        int length,
                        byte[] bytes,
                        boolean sync)
                 throws KernelException

With sync capability

Throws:

KernelException

makePersistent

public void makePersistent(int segmentID)
                    throws UnknownSegmentIDException,
                           AccessDeniedException

The semantics follow AOSapi.makePersistent().

Throws:

UnknownSegmentIDException

AccessDeniedException

finalizeAgentContainer

public void finalizeAgentContainer(boolean sign,
                                   java.security.PrivateKey privateKey,
                                   byte[] certificate)
                            throws KernelException

The semantics follow AOSapi.finalizeAgentContainer(). In addition this method takes the required security parameters.

Parameters:

sign - whether to sign or not (performance measurements)

privateKey - the private key to use for signing

certificate - the X509 public key certicate corresponding to privateKey in PEM format

Throws:

KernelException

isFinalized

public boolean isFinalized()

getFinalizedLength

public long getFinalizedLength()

Returns the length of the finalized agent container last finalized by finalizeAgentContainer(), or -1 if finalizeAgentContainer() has not yet been called.

marshalFinalizedState

public void marshalFinalizedState(java.io.OutputStream outs,
                                  int startOffset,
                                  int endOffset)
                           throws java.io.IOException

Writes the agent container last finalized by finalizeAgentContainer() to a virtual connection. As a precondition, finalizeAgentContainer() must have been called.

Throws:

java.io.IOException

getFinalizedFile

public java.io.File getFinalizedFile()

Used by JUnit and Arno

checkFinalized

public static void checkFinalized(java.io.File acFile,
                                  java.lang.String expectedSCID,
                                  boolean verifyChecksum)
                           throws ACTPACFormatException,
                                  ACTPACVerifyException,
                                  InputOutputException

Check a finalized AC received from a remote kernel. We assume the kernel may be malicious, so we don't trust the input to be correct.

Parameters:

acFile - The file containing the data received from the remote kernel.

expectedSCID - The SCID of the expected sender which must be the signer of the AC

verifyChecksum - If true also check if the checksums match to the corresponding TOC entry. Otherwise it is assumed to be checked somewhere else (createFromFile). It is questionable whether we need to verify the checksums here, as this requires a complete unzip\ of the agent container, something which is also done when extracting the AC.

Throws:

ACTPACFormatException

ACTPACVerifyException

InputOutputException

checkReceipt

public void checkReceipt(java.security.Signature sig,
                         byte[] sigBytes)
                  throws ACTPReceiptException

Throws:

ACTPReceiptException

createFromFile

public void createFromFile(java.io.File acFile,
                           boolean verifyChecksums)
                    throws KernelException

Create an agentcontainer from a file containing a finalized AC received from a remote kernel

Parameters:

acFile - The file containing the finalized AC

verifyChecksums - If the checksums are to be verified. It is more efficient to do that here than instead of in the checkFinalized method, as this method extracts the zip contents anyway.

Throws:

ACTPACFormatException - When the file's format is incorrect.

InputOutputException - Problems reading file from disk.

KernelException

checkOwnerIs

public void checkOwnerIs(Role r)
                  throws AccessDeniedException

Check if the owner is the expected owner

Parameters:

r - the expected role

Throws:

AccessDeniedException - if the AC is not owned by the expected owner

setOwner

public void setOwner(Role r)
              throws KernelException

Specified by:

setOwner in interface KernelResource

Throws:

KernelException

getOwner

public Role getOwner()

Specified by:

getOwner in interface KernelResource