AMETAS.data
Class AMETASSPUContainer

java.lang.Object
  AMETAS.data.AMETASSCContainer
      AMETAS.data.AMETASSPUContainer

All Implemented Interfaces:

java.io.Externalizable, java.io.Serializable

public class AMETASSPUContainer

extends AMETASSCContainer

implements java.io.Externalizable

Bundle of classes, privileges, types, and signatures defining a Place User. The SPU container (also short SPU) contains all classes which are required to get a PU running at a place. All classes are signed with one signature of the author. It is possible to integrate further SPUs in this SPU. These sub-SPUs may be agents which are to be invoked at a remote place using the spawnAgent command.

Sub-SPUs must be completely prepared before they are integrated. That means that all privileges are set as required, all types are set, and all signatures are provided. The integration process may be iterated.

The runtime privileges are the maximum set of privileges during runtime of this Place User. The actual privileges are computed from the user's current privileges intersected with the runtime privileges set. The start privileges are the minimum set of privileges a user must have to start this Place User.

For services, the privileges at runtime are exactly the runtime privileges, regardless of the person causing the service to start. The start privileges are used to define whether messages from a user's PU are accepted or not.

The contents are stored by a zip stream using compression.

Note the terminology: A PU main class is a subclass of AMETASPlaceUser or AMETASServiceObject. The main PU class is the PU main class which is instantiated after loading this SPU; it is the main Place User.

See Also:

Serialized Form

Constructor Summary

AMETASSPUContainer()
Initialization of a SPU container.

Method Summary

boolean	addType(java.lang.String sComponentName, AMETASType type) Adds another type description.
void	addVersion(java.lang.String sVersionName, AMETASType[] aType) Adds another version of this Place User.
void	addVersion(java.lang.String sVersionName, java.lang.String[] asStartPrivilege, java.lang.String[] asRuntimePrivilege, AMETASType[] aType) Adds another version to this SPU.
void	checkValid() Checks the integrity of the SPU.
AMETASSPUContainer	extractSPU(java.lang.String sComponentName) Extracts a previously integrated SPU container.
java.lang.String	getName() Returns the name of the SPU, that is the name of the main PU class.
java.lang.String[]	getRuntimePrivileges(java.lang.String sComponentName) Delivers the set of privileges which may be assigned to any instance of the Place User.
byte[]	getSignableData(int nComponent, boolean bUseHashes) Returns a sequence of bytes to be signed.
AMETASSignature[]	getSignatures(java.lang.String sComponentName) Delivers the list of signatures for the component.
java.lang.String[]	getStartPrivileges(java.lang.String sComponentName) Delivers the set of privileges which a user must have to start this Place User.
AMETASType[]	getTypes(java.lang.String sComponentName) Returns the set of types of the requested component.
void	integrate(AMETASSPUContainer spuSub) Imports the given SPU container into this container.
boolean	isVersion(int nIndex) Determines whether the given component name refers to a version or to another integrated SPU.
boolean	isVersion(java.lang.String sComponent) Determines whether the given component name refers to a version or to another integrated SPU.
void	readExternal(java.io.ObjectInput in) Initializing the SPU from a data stream.
boolean	removeTypes(java.lang.String sComponentName) Removes all type descriptions of the Place User.
void	setReferencedClasses(short[] anReference) Defines the list of classes which are referenced by a Place User.
void	setRuntimePrivileges(int nIndex, java.lang.String[] asPrivileges) Allows to set the list of maximum runtime privileges.
boolean	setRuntimePrivileges(java.lang.String sName, java.lang.String[] asPrivilege) Allows to set the list of maximum runtime privileges.
void	setStartPrivileges(int nIndex, java.lang.String[] asPrivileges) Allows to set the list of required start privileges.
boolean	setStartPrivileges(java.lang.String sName, java.lang.String[] asPrivilege) Allows to set the list of required start privileges.
boolean	setTypes(java.lang.String sComponentName, AMETASType[] aType) Sets the defined types of this Place User (component or version).
java.lang.String	toString() Outputs the contents of the SPU container to a string.
java.lang.String	toString(boolean bDetailed) Outputs the contents of the SPU to a string.
void	wipeClassDefs() Removes the class definitions after they were copied to the cache.
void	writeExternal(java.io.ObjectOutput out) Serialization method.

Methods inherited from class AMETAS.data.AMETASSCContainer

addClass, addFile, addSignature, containsClass, createHash, getAllClassNames, getAllComponents, getBytesFromStream, getClass, getClassAt, getDigestAlgorithm, getHashValue, getHashValueAt, getIndexOfClass, getIndexOfComponent, getNextEntryData, getSignableData, getSignatures, removeSignature, removeSignatures, serializeObject, setCompressionLevel, setDigestAlgorithm, size, writeToZip

Methods inherited from class java.lang.Object

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

Constructor Detail

AMETASSPUContainer

public AMETASSPUContainer()

Initialization of a SPU container. The container is still empty.

Method Detail

readExternal

public void readExternal(java.io.ObjectInput in)
                  throws java.io.IOException,
                         java.lang.ClassNotFoundException

Initializing the SPU from a data stream.

Specified by:

readExternal in interface java.io.Externalizable

Overrides:

readExternal in class AMETASSCContainer

Parameters:

in - Data stream from where the data is read.

Throws:

java.io.IOException - if the stream encounters an error.

java.lang.ClassNotFoundException - if the container uses unknown classes.

writeExternal

public void writeExternal(java.io.ObjectOutput out)
                   throws java.io.IOException

Serialization method.

Specified by:

writeExternal in interface java.io.Externalizable

Overrides:

writeExternal in class AMETASSCContainer

Parameters:

out - Output stream.

Throws:

java.io.IOException - if errors occured in the underlying stream.

integrate

public void integrate(AMETASSPUContainer spuSub)
               throws InvalidContainerException

Imports the given SPU container into this container. The signatures of this container become invalid. All integrated SPUs may be started by spawnAgent.

Parameters:

spuSub - SPU container to be integrated.

Throws:

InvalidContainerException - if the second container cannot be integrated. This happens when this method is attempted to be used in the AMETAS runtime environment (AMETAS-re).

addVersion

public void addVersion(java.lang.String sVersionName,
                       AMETASType[] aType)
                throws InvalidContainerException

Adds another version of this Place User. Versions differ by their privileges and their types and names, but share the same code. The privileges are assumed to be equal to the main version with this method.

Parameters:

sVersionName - Version name. Corresponds to the parametrization name.

aType - Set of types which characterize this version.

Throws:

InvalidContainerException - if the version cannot be added. This happens when this method is attempted to be used in the AMETAS runtime environment (AMETAS-re).

addVersion

public void addVersion(java.lang.String sVersionName,
                       java.lang.String[] asStartPrivilege,
                       java.lang.String[] asRuntimePrivilege,
                       AMETASType[] aType)
                throws InvalidContainerException

Adds another version to this SPU. This method should only be called in the Software Development Kit of AMETAS (AMETAS-sdk).

Parameters:

sVersionName - Version name. Corresponds to the parametrization name.

asStartPrivilege - Start privileges.

asRuntimePrivilege - Runtime privileges.

aType - Set of types characterizing this version.

Throws:

InvalidContainerException - if the version cannot be added. This happens when this method is attempted to be used in the AMETAS runtime environment (AMETAS-re).

isVersion

public boolean isVersion(java.lang.String sComponent)

Determines whether the given component name refers to a version or to another integrated SPU.

Parameters:

sComponent - Component name or null if the main PU (version) is referred to.

Returns:

true if it is a version, else false.

isVersion

public boolean isVersion(int nIndex)

Determines whether the given component name refers to a version or to another integrated SPU.

Parameters:

nIndex - Component or version index.

Returns:

true if it is a version, else false.

extractSPU

public AMETASSPUContainer extractSPU(java.lang.String sComponentName)

Extracts a previously integrated SPU container. When the given name determines a subagent, a SPU is created which only contains the referenced classes. Signatures are also kept for this new agent. This allows to save space and bandwidth because classes are only transported once. This command may be used iteratively if the new SPU contains SPUs by itself.

Parameters:

sComponentName - Class name of the subagent.

Returns:

SPU of the subagent if the class was found, else null.

getName

public java.lang.String getName()

Returns the name of the SPU, that is the name of the main PU class.

Returns:

SPU name.

wipeClassDefs

public void wipeClassDefs()

Removes the class definitions after they were copied to the cache.

setReferencedClasses

public void setReferencedClasses(short[] anReference)

Defines the list of classes which are referenced by a Place User. The main class is passed as the first entry in the array. The referenced class indexes occupy the following array locations.

Parameters:

anReference - Indexes of referenced classes, the main class being at position 0.

checkValid

public void checkValid()
                throws InvalidContainerException

Checks the integrity of the SPU. The SPU container is valid if and only if the list of class references is not empty, if the hash codes of all classes are provided, and if the start and runtime privileges are not empty for each Place User. Moreover, the validity conditions of SCCs must be fulfilled.

Overrides:

checkValid in class AMETASSCContainer

Throws:

InvalidContainerException - if the container fails to validate.

getSignableData

public byte[] getSignableData(int nComponent,
                              boolean bUseHashes)

Returns a sequence of bytes to be signed. This sequence is immutable unless this SPU container is changed by adding components or classes or changing privileges and types.

Parameters:

nComponent - Component index.

bUseHashes - if true, only the digests of the classes are used; the classes themselves are ignored.

Returns:

Array of bytes to be signed.

getSignatures

public AMETASSignature[] getSignatures(java.lang.String sComponentName)

Delivers the list of signatures for the component.

Parameters:

sComponentName - Class name of the enclosed (or main) Place User. Null refers to the main PU class.

Returns:

Array of corresponding signatures.

getStartPrivileges

public java.lang.String[] getStartPrivileges(java.lang.String sComponentName)

Delivers the set of privileges which a user must have to start this Place User.

Parameters:

sComponentName - Class name of the enclosed (or main) Place User. Null refers to the main PU class.

Returns:

Array of privileges or null if the component was not found.

getRuntimePrivileges

public java.lang.String[] getRuntimePrivileges(java.lang.String sComponentName)

Delivers the set of privileges which may be assigned to any instance of the Place User. The actual privileges will be derived from intersecting with the user's own privileges.

Parameters:

sComponentName - Class name of the enclosed (or main) Place User. Null refers to the main PU class.

Returns:

Array of privileges which this Place User may get at maximum, or null if the component was not found.

setStartPrivileges

public boolean setStartPrivileges(java.lang.String sName,
                                  java.lang.String[] asPrivilege)

Allows to set the list of required start privileges. The signatures will be lost.

Parameters:

sName - Class name of the enclosed (or main) Place User. Null referes to the main PU version.

asPrivilege - Array of privileges.

Returns:

true if the privileges could be set, else false (if the component was not found).

setStartPrivileges

public void setStartPrivileges(int nIndex,
                               java.lang.String[] asPrivileges)
                        throws java.lang.IndexOutOfBoundsException

Allows to set the list of required start privileges. The signatures will be lost.

Parameters:

nIndex - Component index.

asPrivileges - String array containing the privileges.

Throws:

java.lang.IndexOutOfBoundsException - if the index is not smaller than the number of components.

setRuntimePrivileges

public boolean setRuntimePrivileges(java.lang.String sName,
                                    java.lang.String[] asPrivilege)

Allows to set the list of maximum runtime privileges. The signatures will be lost.

Parameters:

sName - Class name of the enclosed (or main) Place User. Null refers to the main version.

asPrivilege - Array of privileges.

Returns:

true if the privileges could be set, else false (if the component was not found).

setRuntimePrivileges

public void setRuntimePrivileges(int nIndex,
                                 java.lang.String[] asPrivileges)
                          throws java.lang.IndexOutOfBoundsException

Allows to set the list of maximum runtime privileges. The signatures will be lost.

Parameters:

nIndex - Component index.

asPrivileges - String array containing the privileges.

Throws:

java.lang.IndexOutOfBoundsException - if the index is not smaller than the number of components.

getTypes

public AMETASType[] getTypes(java.lang.String sComponentName)

Returns the set of types of the requested component. Each component may have more than one type, especially for use with different mediators. The parametrization of a Place User may be given as "MyService#P1".

Parameters:

sComponentName - Place User name, including its parametrization if applicable. Using null yields the main PU version types.

Returns:

Types of this Place User according to the parametrization.

setTypes

public boolean setTypes(java.lang.String sComponentName,
                        AMETASType[] aType)

Sets the defined types of this Place User (component or version).

Parameters:

sComponentName - PU main class name with parametrization (if applicable). Null refers to the main Place User.

aType - Type descriptions.

Returns:

true if the types could be set, else false (if the index is invalid).

addType

public boolean addType(java.lang.String sComponentName,
                       AMETASType type)

Adds another type description. Each Place User may have different types, especially for use with different mediators.

Parameters:

sComponentName - Component or version name, or null if the main Place User is requested.

type - Type description.

Returns:

true if the type could be added, else false (if the index is invalid).

removeTypes

public boolean removeTypes(java.lang.String sComponentName)

Removes all type descriptions of the Place User. The enclosed Place Users are not affected.

Parameters:

sComponentName - PU main class, including the parametrization if applicable. Null refers to the main version.

Returns:

true if the version was found, else false.

toString

public java.lang.String toString()

Outputs the contents of the SPU container to a string.

Overrides:

toString in class AMETASSCContainer

Returns:

String representation.

toString

public java.lang.String toString(boolean bDetailed)

Outputs the contents of the SPU to a string.

Overrides:

toString in class AMETASSCContainer

Parameters:

bDetailed - if true, details are included, else the simple toString method is used.

Returns:

String representation.