AMETAS.place
Class AMETASPlace

java.lang.Object
  AMETAS.place.AMETASPlace

public final class AMETASPlace

extends java.lang.Object

The place. This is the central object of the AMETAS agent system. The place instance contains vital functions of the infrastructure.

Field Summary

static java.lang.String	IDENTITIES Subdirectory which contains identity files.
static byte	INITIALIZING Place initializing state.
static java.lang.String	LOGS Subdirectory containing log files.
static byte	READY Place ready state.
static byte	SHUTTING_DOWN Place shutting down state.

Method Summary

java.lang.String	configToString() Returns a string representation of the local configuration.
void	dumpCurrentMessages() Outputs all messages in the Post Office to the place log.
AMETAS.place.AMETASAccessMonitor	getAccessMonitor() Returns a reference to the AccessMonitor.
AMETAS.place.AMETASAccountManager	getAccountManager() Returns a reference to the AccountManager.
AMETASPlaceNameService	getDefaultPNS() Returns a PlaceNameService accessor object with the settings of this place.
java.lang.String	getFilesDir() Returns the path to the miscellaneous files directory.
java.lang.String	getHostName() Delivers the fully qualified host name.
AMETASIdentityDataBase	getIdentityDataBase() Returns the reference to the identity database.
java.lang.String	getIdentityDir() Returns the path to the identities directory.
PNSAddress	getLocation() Returns the PNS location of this place.
java.lang.String	getLogDir() Returns the path to the place log files.
java.lang.Object	getObject(java.lang.String sOID) Delivers the value of a management object.
java.lang.String	getPlaceDir() Returns the path to the place base directory.
java.lang.String	getPlaceName() Delivers the fully qualified place name.
AMETASPlaceUserID	getPlacePUID() Returns the Place User ID of the place.
java.lang.String[]	getPlaceUserPath() Returns the Place User Path as an array of path components.
java.lang.String	getPolicyDir() Returns the path of the policy directory.
AMETASPolicyManager	getPolicyManager() Returns a reference to the policy manager.
int	getPortNumber() Returns the agent port number.
long	getRepLinger() Returns the type description timeout.
byte	getState() Delivers the current state of the place.
int	getUIPort() Returns the port number for user interfaces.
void	killPlaceUser(AMETASIdentityID iidKiller, AMETASPlaceUserID puidKiller, AMETASPlaceUserID puidVictim, long nTimeout) Puts a Place User on the list of Place Users to be killed.
static void	main(java.lang.String[] args) Main method to start the place.
java.lang.String	messagesToString() Returns a string representation of the messages in the Post Office.
void	setObject(java.lang.String sOID, java.lang.Object objValue) Sets a management object to some value.
void	trace(java.lang.String sTraceMessage) Outputs debug messages.
void	trace(java.lang.String sTraceMessage, AMETASPlaceUserID puidPU) Outputs debug messages.
void	trace(java.lang.String sTraceMessage, java.lang.Throwable e) Outputs debug messages.
byte	updateProperty(java.lang.String sName, java.lang.String sValue) Updates a place property value.
void	writeProperties() Writes the place configuration to the config file.

Methods inherited from class java.lang.Object

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

Field Detail

IDENTITIES

public static final java.lang.String IDENTITIES

Subdirectory which contains identity files.

See Also:

Constant Field Values

LOGS

public static final java.lang.String LOGS

Subdirectory containing log files.

See Also:

Constant Field Values

READY

public static final byte READY

Place ready state.

See Also:

Constant Field Values

INITIALIZING

public static final byte INITIALIZING

Place initializing state.

See Also:

Constant Field Values

SHUTTING_DOWN

public static final byte SHUTTING_DOWN

Place shutting down state.

See Also:

Constant Field Values

Method Detail

main

public static void main(java.lang.String[] args)

Main method to start the place. The call syntax looks as follows:

java -DDNS_HOSTNAME=HostName AMETAS.place.AMETASPlace ConfigFile

Make sure that your classpath contains the JAR file of the AMETAS distribution. The host name must be explicitely defined because Java does not offer a reliable means of determining the fully qualified host name.

Parameters:

args - Must contain a place configuration file pathname at the first position. Remaining parameters are ignored.

getState

public byte getState()

Delivers the current state of the place. The agent port may use this value to determine whether agents may immigrate currently or not.

Returns:

Place state (READY, INITIALIZING, SHUTTING_DOWN)

Since:

2.3.0

writeProperties

public void writeProperties()
                     throws java.io.IOException

Writes the place configuration to the config file.

Throws:

java.io.IOException - if there were problems while writing the properties.

updateProperty

public byte updateProperty(java.lang.String sName,
                           java.lang.String sValue)
                    throws java.lang.SecurityException

Updates a place property value. The new value may be received from the AMAI interface. Some properties require a restart (e.g. the PNS-related values). Using this method requires administrative permissions.

Parameters:

sName - Property name.

sValue - Property value.

Returns:

AMETASErrors.OK if the value was good; AMETASErrors.BAD_PARAMS if the value was bad; AMETASErrors.DEFERRED if the value was good and a restart of the place is required to take effect.

Throws:

java.lang.SecurityException - if the caller does not have administrative permissions.

getPlaceName

public java.lang.String getPlaceName()

Delivers the fully qualified place name.

Returns:

Place name.

getHostName

public java.lang.String getHostName()

Delivers the fully qualified host name. This is exactly the value as given on place startup, so there is no guarantee that this information is really authoritative.

Returns:

Host name.

getPortNumber

public int getPortNumber()

Returns the agent port number.

Returns:

Agent port number.

getLocation

public PNSAddress getLocation()

Returns the PNS location of this place. The PNS location contains the host name and port number.

Returns:

PNS location of this place.

getPlacePUID

public AMETASPlaceUserID getPlacePUID()

Returns the Place User ID of the place. This PUID is required to allow for message submission by the place.

Returns:

PlaceUserID of the place.

getUIPort

public int getUIPort()

Returns the port number for user interfaces.

Returns:

UI port to be used to connect by AMAI or AMSI.

getAccessMonitor

public AMETAS.place.AMETASAccessMonitor getAccessMonitor()
                                                  throws java.lang.SecurityException

Returns a reference to the AccessMonitor.

Returns:

Access monitor.

Throws:

java.lang.SecurityException - if the caller does not have administrative permissions.

getPolicyManager

public AMETASPolicyManager getPolicyManager()
                                     throws java.lang.SecurityException

Returns a reference to the policy manager.

Returns:

Policy manager.

Throws:

java.lang.SecurityException - if the caller does not have administrative permissions.

getAccountManager

public AMETAS.place.AMETASAccountManager getAccountManager()
                                                    throws java.lang.SecurityException

Returns a reference to the AccountManager.

Returns:

Account manager.

Throws:

java.lang.SecurityException - if the caller does not have administrative permissions.

getIdentityDataBase

public AMETASIdentityDataBase getIdentityDataBase()
                                           throws java.lang.SecurityException

Returns the reference to the identity database.

Returns:

Identity database.

Throws:

java.lang.SecurityException - if the caller does not have administrative permissions.

getRepLinger

public long getRepLinger()

Returns the type description timeout. The timeout happens after the agent left the place for this period of time.

Returns:

Time period in milliseconds.

getPolicyDir

public java.lang.String getPolicyDir()

Returns the path of the policy directory. This is currenty identical to the place base directory.

Returns:

Path.

getIdentityDir

public java.lang.String getIdentityDir()

Returns the path to the identities directory.

Returns:

Path.

getPlaceDir

public java.lang.String getPlaceDir()

Returns the path to the place base directory.

Returns:

Place base directory.

getLogDir

public java.lang.String getLogDir()

Returns the path to the place log files.

Returns:

Path.

getFilesDir

public java.lang.String getFilesDir()

Returns the path to the miscellaneous files directory.

Returns:

Path.

getPlaceUserPath

public java.lang.String[] getPlaceUserPath()

Returns the Place User Path as an array of path components.

Returns:

PU path as a String array.

dumpCurrentMessages

public void dumpCurrentMessages()
                         throws java.lang.SecurityException

Outputs all messages in the Post Office to the place log.

Throws:

java.lang.SecurityException - if the caller does not have administrative permissions.

messagesToString

public java.lang.String messagesToString()
                                  throws java.lang.SecurityException

Returns a string representation of the messages in the Post Office. This may be used for debugging purposes (e.g. in AMAI).

Returns:

Representation of all messages as a single string.

Throws:

java.lang.SecurityException - if the caller does not have administrative permissions.

configToString

public java.lang.String configToString()
                                throws java.lang.SecurityException

Returns a string representation of the local configuration.

Returns:

Place configuration as a string.

Throws:

java.lang.SecurityException - if the caller does not have administrative permissions.

getDefaultPNS

public AMETASPlaceNameService getDefaultPNS()

Returns a PlaceNameService accessor object with the settings of this place.

Returns:

Reference to a new PNS accessor object.

killPlaceUser

public void killPlaceUser(AMETASIdentityID iidKiller,
                          AMETASPlaceUserID puidKiller,
                          AMETASPlaceUserID puidVictim,
                          long nTimeout)

Puts a Place User on the list of Place Users to be killed. This action is allowed to administrators as well as to the Place User owners. If the requoestor is not entitled to kill this Place User, a PLACEERROR is generated. This method is public so that services may access it.

Parameters:

iidKiller - IdentityID of the user who wants to kill the Place User. Administrators are represented by a null.

puidKiller - ID of the Place User which submitted the termination request.

puidVictim - Place User which is requested to be terminated.

nTimeout - Period of time until this request becomes outdated.

trace

public void trace(java.lang.String sTraceMessage)

Outputs debug messages. Depending on the debug state of the place, messages are discarded or printed to the log.

Parameters:

sTraceMessage - Message to be printed.

trace

public void trace(java.lang.String sTraceMessage,
                  AMETASPlaceUserID puidPU)

Outputs debug messages. Depending on the debug state of the place, messages are discarded or printed to the log. This method causes a withdrawal from the sender's account.

Parameters:

sTraceMessage - Message to be printed.

puidPU - ID of the outputting Place User.

trace

public void trace(java.lang.String sTraceMessage,
                  java.lang.Throwable e)

Outputs debug messages. This method is normally used for error tracing. The stack trace will be printed to the place log. The length of the stack trace will be limited to 30*80 characters by removing intermediate lines.

Parameters:

sTraceMessage - Message to be output.

e - Exception or error the stack trace of which shall be printed.

getObject

public java.lang.Object getObject(java.lang.String sOID)
                           throws java.lang.Exception

Delivers the value of a management object.

Parameters:

sOID - Object ID of the MO.

Throws:

java.lang.Exception - if some problems occured while reading the MO or the ID is unknown.

Since:

2.5.0

setObject

public void setObject(java.lang.String sOID,
                      java.lang.Object objValue)
               throws java.lang.Exception

Sets a management object to some value. This method may currently only be used to set values of the group ametas.place.info.

Parameters:

sOID - Object ID of the MO.

objValue - New value of the MO.

Throws:

java.lang.Exception - if there were problems while setting the value or when the ID refers to some other MO.

Since:

2.5.0