AMETAS.place
Interface AMETASPlaceUserDriverIf

All Known Subinterfaces:

AMETASAgentDriverIf, AMETASServiceManagerDriverIf, AMETASUserAdapterDriverIf

public interface AMETASPlaceUserDriverIf

Interface to the Place User Driver. This interface collects methods needed by all Place Users. When developing agents, user adapters, or services, the interface from the respective package must be used. The driver will be made accessible to the Place User before it is invoked. The driver interface decouples the Place User from the kernel. The Place User may not gain direct access to internal components. All kernel functionality is only accessible via this driver interface.

Method Summary

void	addPUType(AMETASType type) Adds a new type description at runtime.
AMETASType	createTypeForString(java.lang.String sString) Creates a runtime representation of the type description.
AMETASType	createTypeForString(java.lang.String sString, java.lang.String sMode) Creates a runtime representation of the type description.
byte	deleteMessage(AMETASMessageID mid) Removes a message from the PostOffice.
byte	depositMessage(AMETASMessage mesNewMessage) Deposits a message in the PostOffice.
byte	depositMessage(AMETASPlaceUserID idReceiver, java.lang.Object[] aBody) Deposits a message in the PostOffice.
byte	depositRemoteMessage(AMETASMessage mesNewMessage, java.lang.String sDestPlaceName) Deprecated. Use messenger agents for remote message delivery.
boolean	fullPrivileges() Determines whether the Place User received all privileges.
java.lang.Class	getClass(java.lang.String sClassName) Deprecated. This method does not do more than Class.forName(String) can do as well.
java.lang.String	getDestinationPlace(AMETASMediationResult descr) Delivers the place where a mediated agent departed to.
java.lang.String	getDestinationPlace(AMETASPlaceUserID puid) Delivers the place where a mediated agent departed to.
byte[]	getFile(java.lang.String sFileName) Allows the Place User to load an included file.
java.lang.String	getHostName() Returns the fully qualified host name of this place.
long	getLeavingTime(AMETASMediationResult descr) Returns the time since a given Place User left the place.
long	getLeavingTime(AMETASPlaceUserID puid) Returns the time since a given Place User left the place.
MediatorInfo	getMediatorInfo() Returns information about the mediator.
AMETASMessage[]	getMessages(boolean bDeleteIfPossible) Retrieves all messages from the PostOffice which are relevant for this PlaceUser.
AMETASMessage[]	getMessages(boolean bDeleteIfPossible, AMETASMessageMask mesm) Retrieves all messages relevant for this PlaceUser and matching the given message mask.
java.util.Vector	getMessagesAsVector(boolean bDeleteIfPossible) Retrieves all messages relevant for this PlaceUser as a vector.
java.util.Vector	getMessagesAsVector(boolean bDeleteIfPossible, AMETASMessageMask mesm) Retrieves all messages relevant for this PlaceUser and matching the given mask as a vector.
AMETASPermissionList	getPermissionList(AMETASPrivilegeList prl) Returns the list of permissions of a given privilege list.
java.lang.String	getPlaceName() Delivers the name of the place where this Place User currently resides.
AMETASPlaceUserID	getPlaceUserID() Returns the Place User ID of this Place User.
AMETASPrivilegeList	getPrivileges() Returns the privileges which were delegated to this Place User.
AMETASType[]	getPUTypes() Returns the types of this Place User.
AMETASSecurityFeature	getSecurityFeature() Retrieves the security features.
AMETASIdentityID	getStarterID(AMETASMediationResult mrs) Returns the starter of the given Place User.
AMETASType[]	getTypesOf(AMETASPlaceUserID puid) Returns the set of types of some running Place User.
AMETASType[]	getTypesOf(java.lang.String sRegistered) Returns the types of the some registered Place User.
boolean	idle(long nMillis) Allows the driver to sleep for some time.
void	killPlaceUser(AMETASPlaceUserID puid, long nValidity) Attempts to stop a Place User.
void	output(java.lang.String sText) Outputs a string message to the place log.
boolean	privilegeGranted(java.lang.String sPrivilegeName) Determines whether the Place User got the given privilege.
void	registerEventListener(int nEventID, int nOptions, java.lang.Object[] objArgs) Registers the Place User for incoming events.
void	registerEventListener(int nEventID, java.lang.Object[] objArgs) Registers the Place User for incoming events.
void	registerEventListener(int nEventID, short nMinPriority, int nOptions, java.lang.Object[] objArgs) Registers the Place User for incoming events.
AMETASMessageMask	registerServiceResponseListener(AMETASPlaceUserID idService) Convenience method to simplify event registration.
AMETASMediationResult[]	request(AMETASMediationRequest req) Sends a request to the local mediator.
AMETASMediationResult[]	request(AMETASMediationRequest req, AMETASPlaceUserIDMask puidm, AMETASIdentityID iid) Sends a request to the local mediator.
AMETASPlaceUserID	requestPUStartup(AMETASMediationResult mrs, AMETASMessage msgInit) Requests the place to start a Place User.
AMETASPlaceUserID	requestPUStartup(java.lang.String sSPUName, AMETASMessage msgInit) Requests the place to start a Place User.
void	requestService_WaitAndUnregister(AMETASPlaceUserID idService, java.lang.Object[] aobjParams, AMETASMessageMask mesmServiceResponse, long nWaitTime) Convenience method for service access.
void	requestService_WaitAndUnregister(AMETASPlaceUserID idService, java.util.Vector vctParams, AMETASMessageMask mesmServiceResponse, long nWaitTime) Deprecated. Use the Object[] version of this method.
boolean	setSecurityFeature(AMETASSecurityFeature sf) Defines the security features for this Place User.
AMETASPlaceUserID	spawnAgent(java.lang.String sSubAgent, AMETASMessage msgInit) Starts a contained Place User.
boolean	stillPresent(AMETASMediationResult descr) Determines whether a given Place User is still running at this place.
boolean	stillPresent(AMETASPlaceUserID puid) Determines whether a given Place User is still running at this place.
void	stopDriver() Deprecated. This method uses the deprecated Thread.stop method. The Place User should terminate by letting all threads halt and leaving the invoke method.
void	stopPlace() Stops the place where this Place User is currently running.
boolean	suitableForMediator(AMETASType type) Deterines whether the local mediator may process the given type.
void	trace(java.lang.String sText) Used to output debug messages.
boolean	unknownPrivileges() Determines whether this Place User requested unknown privileges.
void	unregisterEventListener(int nEventID, java.lang.Object[] objArgs) Unregisters the Place User for the specified event.
void	updateRegistration() Causes a new type registration for this Place User.
void	useRequestedService(AMETASPlaceUserID idService, java.lang.Object[] aobjParams, long nWaitTime) Convenience method for service access.
void	useRequestedService(AMETASPlaceUserID idService, java.util.Vector vctParams, long nWaitTime) Deprecated. Use the Object[] version
void	wakeup() Wakes up the driver.

Method Detail

depositMessage

public byte depositMessage(AMETASPlaceUserID idReceiver,
                           java.lang.Object[] aBody)

Deposits a message in the PostOffice. This convenience method creates an AMETAS message instance.

Parameters:

idReceiver - ID of the recipient.

aBody - Payload of the message.

Returns:

AMETASErrors.OK, if the message was deposited correctly, else an error code.

depositMessage

public byte depositMessage(AMETASMessage mesNewMessage)

Deposits a message in the PostOffice.

Parameters:

mesNewMessage - Message to be deposited.

Returns:

AMETASErrors.OK, if the message was deposited correctly, else an error code.

depositRemoteMessage

public byte depositRemoteMessage(AMETASMessage mesNewMessage,
                                 java.lang.String sDestPlaceName)

Deprecated. Use messenger agents for remote message delivery.

Deposits a message in the PostOffice of a remote place. This is done unencrypted so that you should rather use agents for security reasons. Every message that may be deposited locally may also be deposited remotely. The sender must specify the place where the message shall be sent to. All details are handled by the subsystem.

Parameters:

mesNewMessage - Message to be deposited remotely.

sDestPlaceName - Destination place.

Returns:

AMETASErrors.OK, if the message was deposited successfully; AMETASErrors.NOT_FOUND, if the remote place is unknown; AMETASErrors.NOT_ENOUGH_ACCOUNT, if the sender runs out of account; AMETASErrors.ACCESS_DENIED, if the remote depositing is not allowed for this sender.

getMessages

public AMETASMessage[] getMessages(boolean bDeleteIfPossible)

Retrieves all messages from the PostOffice which are relevant for this PlaceUser.

Parameters:

bDeleteIfPossible - if true, messages may be deleted after retrieving.

Returns:

Array of incoming messages or null if there are no messages.

getMessages

public AMETASMessage[] getMessages(boolean bDeleteIfPossible,
                                   AMETASMessageMask mesm)

Retrieves all messages relevant for this PlaceUser and matching the given message mask.

Parameters:

bDeleteIfPossible - if true, messages may be deleted after retrieving.

mesm - Mask to filter uninteresting messages.

Returns:

Array of incoming messages or null if there are no messages.

getMessagesAsVector

public java.util.Vector getMessagesAsVector(boolean bDeleteIfPossible)

Retrieves all messages relevant for this PlaceUser as a vector.

Parameters:

bDeleteIfPossible - if true, messages may be deleted after retrieving.

Returns:

Vector of incoming messages or null if there are no messages.

getMessagesAsVector

public java.util.Vector getMessagesAsVector(boolean bDeleteIfPossible,
                                            AMETASMessageMask mesm)

Retrieves all messages relevant for this PlaceUser and matching the given mask as a vector.

Parameters:

bDeleteIfPossible - if true, messages may be deleted after retrieving.

mesm - Mask to filter uninteresting messages.

Returns:

Vector of incoming messages or null if there are no messages.

deleteMessage

public byte deleteMessage(AMETASMessageID mid)

Removes a message from the PostOffice.

Parameters:

mid - ID of the message to be removed.

Returns:

AMETASErrors.OK if successful; AMETASErrors.ACCESS_DENIED if the Place User must not remove this message. AMETASErrors.NOT_FOUND if there is no message with the given ID.

getPlaceName

public java.lang.String getPlaceName()

Delivers the name of the place where this Place User currently resides.

Returns:

Name of the current place.

getHostName

public java.lang.String getHostName()

Returns the fully qualified host name of this place.

Returns:

Host name including DNS domain.

requestPUStartup

public AMETASPlaceUserID requestPUStartup(java.lang.String sSPUName,
                                          AMETASMessage msgInit)
                                   throws CreationFailedException,
                                          CreationDeniedException

Requests the place to start a Place User. This depends on the actual privileges of the requesting Place User. For services, the SPU name may be appended by the so-called version name (like MyService#version1).

Parameters:

sSPUName - SPU name (including version name)

msgInit - Message to be sent to the newly created Place User instance for initialization.

Returns:

ID of the new Place User.

Throws:

CreationFailedException - if the startup failed (e.g. invalid SPU container).

CreationDeniedException - if the requestor does not have enough privileges.

requestPUStartup

public AMETASPlaceUserID requestPUStartup(AMETASMediationResult mrs,
                                          AMETASMessage msgInit)
                                   throws CreationFailedException,
                                          CreationDeniedException

Requests the place to start a Place User. This depends on the actual privileges of the requesting Place User.

Parameters:

mrs - Result of a previous mediation request.

msgInit - Message to be sent to the newly created Place User instance for initialization.

Returns:

ID of the new Place User.

Throws:

CreationFailedException - if the startup failed (e.g. invalid SPU container).

CreationDeniedException - if the requestor does not have enough privileges.

spawnAgent

public AMETASPlaceUserID spawnAgent(java.lang.String sSubAgent,
                                    AMETASMessage msgInit)
                             throws CreationFailedException,
                                    CreationDeniedException

Starts a contained Place User. The Place User is included in the SPU container of this requesting Place User. Only agents may be spawed by this method, and you can only use their name, not any mediation result. (Why should you anyway, when the agent is included in your backback?)

Parameters:

sSubAgent - Agent to be started.

msgInit - Optional initialization message.

Returns:

ID of the new agent.

Throws:

CreationFailedException - if the startup failed (e.g. invalid SPU container).

CreationDeniedException - if the requestor does not have enough privileges.

output

public void output(java.lang.String sText)

Outputs a string message to the place log.

Parameters:

sText - Text to be output.

trace

public void trace(java.lang.String sText)

Used to output debug messages. The place decides where these messages actually appear. (Although there are no reports that the place would write the output anywhere else than into the log file.) In the place config file, the property TraceOutput may be set to 'on' or 'off' to turn on or off the output by this method.

Parameters:

sText - Debug message to be output.

idle

public boolean idle(long nMillis)

Allows the driver to sleep for some time. Use this method instead of Thread.suspend.

Parameters:

nMillis - Milliseconds of sleeping.

Returns:

true if the thread was waked up by a wakeup operation, else false (if it woke up after the specified time).

wakeup

public void wakeup()

Wakes up the driver. The driver must be put to sleep with idle.

stopDriver

public void stopDriver()

Deprecated. This method uses the deprecated Thread.stop method. The Place User should terminate by letting all threads halt and leaving the invoke method.

Stops the driver and so kills the Placer User. This method may be used as an exit point in the code. All cleanup operations are performed before stopping the driver thread.

killPlaceUser

public void killPlaceUser(AMETASPlaceUserID puid,
                          long nValidity)

Attempts to stop a Place User. This is done by putting the Place User ID on a "blacklist". When it (as an agent) arrives at this place, it will be accepted but not started and will thus be discarded. If the Place User is present at this place, it will be directly stopped. The identity of the requestor will be stored to find out before killing whether the identity has the privilege to stop this Place User. A Place User may be stopped by the identity who started it or by the (local) administrator.

Parameters:

puid - ID of the Place User to be stopped.

nValidity - Milliseconds until the stop request will be discarded.

stopPlace

public void stopPlace()
               throws AMETASSecurityException

Stops the place where this Place User is currently running.

Throws:

AMETASSecurityException - if the Place User does not have ADMIN privileges.

getPrivileges

public AMETASPrivilegeList getPrivileges()

Returns the privileges which were delegated to this Place User.

Returns:

List of privileges.

Since:

2.6.0

getPermissionList

public AMETASPermissionList getPermissionList(AMETASPrivilegeList prl)

Returns the list of permissions of a given privilege list. To retrieve the associated permissions, the current domain access policy is accessed.

Parameters:

prl - Privilege list.

Returns:

List of implied permissions.

Since:

2.6.0

fullPrivileges

public boolean fullPrivileges()

Determines whether the Place User received all privileges. This is compared between the runtime privileges and the actual privileges, depending on the privileges of the user.

Returns:

true if all runtime privileges were assigned, else false.

unknownPrivileges

public boolean unknownPrivileges()

Determines whether this Place User requested unknown privileges. There may be privileges defined in the SPU container which are undefined at the local place.

Returns:

true if a privilege was unknown, else false.

privilegeGranted

public boolean privilegeGranted(java.lang.String sPrivilegeName)

Determines whether the Place User got the given privilege.

Parameters:

sPrivilegeName - Name of the privilege.

Returns:

true if the Place User received this privilege, else false.

Since:

2.5.0

setSecurityFeature

public boolean setSecurityFeature(AMETASSecurityFeature sf)

Defines the security features for this Place User. Currently this only affects the migration security and remote signing.

Parameters:

sf - Security features.

Returns:

true if the features are valid, else false.

getSecurityFeature

public AMETASSecurityFeature getSecurityFeature()

Retrieves the security features. Currently this only affects the migration security and remote signing.

Returns:

Security features.

getTypesOf

public AMETASType[] getTypesOf(AMETASPlaceUserID puid)

Returns the set of types of some running Place User.

Parameters:

puid - PUID of the Place User.

Returns:

Types of the Place User or null if there is no such Place User.

getTypesOf

public AMETASType[] getTypesOf(java.lang.String sRegistered)

Returns the types of the some registered Place User.

Parameters:

sRegistered - Registration name of the Place User.

Returns:

Types of the Place User or null if there is no such Place User.

getPUTypes

public AMETASType[] getPUTypes()

Returns the types of this Place User. Each Place User may have different types, especially for different mediators.

Returns:

Types of this Place User.

addPUType

public void addPUType(AMETASType type)

Adds a new type description at runtime.

Parameters:

type - New type.

suitableForMediator

public boolean suitableForMediator(AMETASType type)

Deterines whether the local mediator may process the given type.

Parameters:

type - Type.

Returns:

true if the mediator understands the type description, else false.

getFile

public byte[] getFile(java.lang.String sFileName)
               throws java.io.FileNotFoundException

Allows the Place User to load an included file. The file must be packed into the SPU container or into any imported SCC. If found, the contents are presented as a byte array.

Parameters:

sFileName - File name as provided when packing the container.

Returns:

File contents.

Throws:

java.io.FileNotFoundException - if the file was not found.

Since:

2.6.0

request

public AMETASMediationResult[] request(AMETASMediationRequest req)

Sends a request to the local mediator. The mediator takes the provided type description and returns a list of matching Place Users. You may use this method to retrieve a list of currently running Place Users. Note that agents may have left the place in the meantime. The property RepositoryLinger in the place configuration determines how long the entry for the departed agent will be kept.

Parameters:

req - Instance or type mediation request. If null, all currently running Place Users are returned.

Returns:

List of matching Place Users; empty list for none found; null for an error in mediation.

request

public AMETASMediationResult[] request(AMETASMediationRequest req,
                                       AMETASPlaceUserIDMask puidm,
                                       AMETASIdentityID iid)

Sends a request to the local mediator. The mediator takes the provided type description and returns a list of matching Place Users. You may use this method to retrieve a list of currently running Place Users. Note that agents may have left the place in the meantime. The property RepositoryLinger in the place configuration determines how long the entry for the departed agent will be kept. The PUID mask and the identity ID are used to filter the result list.

Parameters:

req - Instance or type mediation request. If null, all currently running Place Users are returned.

puidm - Mask which is used to filter the results.

iid - Identity used to filter away all results which belong to Place Users not started by this ID.

Returns:

List of matching Place Users; empty list for none found; null for an error in mediation.

Since:

2.3.0

stillPresent

public boolean stillPresent(AMETASMediationResult descr)

Determines whether a given Place User is still running at this place. This may be used by agents leaving the place and returning in order to avoid asking the mediator again.

Parameters:

descr - Result of a previous mediation.

Returns:

true if the Place User is still present, else false.

stillPresent

public boolean stillPresent(AMETASPlaceUserID puid)

Determines whether a given Place User is still running at this place. This may be used by agents leaving the place and returning in order to avoid asking the mediator again.

Parameters:

puid - Place User ID.

Returns:

true if the Place User is still present, else false.

getLeavingTime

public long getLeavingTime(AMETASMediationResult descr)
                    throws java.util.NoSuchElementException

Returns the time since a given Place User left the place. This only applies to agents which have migrated. Terminated Place Users do not have any leaving time because they will never come back (with with this Place User ID).

Parameters:

descr - Result of a previous mediation.

Returns:

Time in milliseconds since when the agent left the place.

Throws:

java.util.NoSuchElementException - if the Place User was terminated or the agent was absent for a too long time.

getLeavingTime

public long getLeavingTime(AMETASPlaceUserID puid)
                    throws java.util.NoSuchElementException

Returns the time since a given Place User left the place. This only applies to agents which have migrated. Terminated Place Users do not have any leaving time because they will never come back (with with this Place User ID).

Parameters:

puid - Place User ID.

Returns:

Time in milliseconds since when the agent left the place.

Throws:

java.util.NoSuchElementException - if the Place User was terminated or the agent was absent for a too long time.

getDestinationPlace

public java.lang.String getDestinationPlace(AMETASMediationResult descr)
                                     throws java.util.NoSuchElementException

Delivers the place where a mediated agent departed to.

Parameters:

descr - result of a previous mediation.

Returns:

Destination place name or null if the Place User is still here.

Throws:

java.util.NoSuchElementException - if the Place User was terminated or the agent was absent for a too long time.

Since:

2.5.0

getDestinationPlace

public java.lang.String getDestinationPlace(AMETASPlaceUserID puid)
                                     throws java.util.NoSuchElementException

Delivers the place where a mediated agent departed to.

Parameters:

puid - Place User ID.

Returns:

Destination place name or null if the Place User is still here.

Throws:

java.util.NoSuchElementException - if the Place User was terminated or the agent was absent for a too long time.

Since:

2.5.0

getStarterID

public AMETASIdentityID getStarterID(AMETASMediationResult mrs)

Returns the starter of the given Place User.

Parameters:

mrs - Result of a previous mediation.

Returns:

ID of the starter or null if the Place User is not here or if the starter may not be determined.

createTypeForString

public AMETASType createTypeForString(java.lang.String sString,
                                      java.lang.String sMode)
                               throws TypeException

Creates a runtime representation of the type description. This creation depends on the capabilities of the active mediator.

Parameters:

sString - String representation of the type.

sMode - Mediator-dependent mode selection.

Returns:

New type instance.

Throws:

TypeException - if the type instance creation failed.

createTypeForString

public AMETASType createTypeForString(java.lang.String sString)
                               throws TypeException

Creates a runtime representation of the type description. This creation depends on the capabilities of the active mediator. The mediator mode is set to be the default mode.

Parameters:

sString - String representation of the type.

Returns:

New type instance.

Throws:

TypeException - if the type instance creation failed.

getMediatorInfo

public MediatorInfo getMediatorInfo()

Returns information about the mediator. The Place User may then decide how to formulate the type request or which mode to use.

Returns:

Meditator information.

getPlaceUserID

public AMETASPlaceUserID getPlaceUserID()

Returns the Place User ID of this Place User. This method is needed by components which have access to the driver but are not located in this package (like the context API classes).

Returns:

ID of this Place User.

Since:

2.6.0

getClass

public java.lang.Class getClass(java.lang.String sClassName)
                         throws java.lang.ClassNotFoundException

Deprecated. This method does not do more than Class.forName(String) can do as well.

Loads a class for the Place User. The class file is searched in the SPU container and all imported class containers. If it is found, it will be loaded and a Class instance is returned which may be used in newInstance calls. Otherwise, a ClassNotFoundException is tossed at the caller.

Parameters:

sClassName - Fully qualified name of the class.

Returns:

Loaded class.

Throws:

java.lang.ClassNotFoundException - if the class was not found.

updateRegistration

public void updateRegistration()

Causes a new type registration for this Place User. This may be required after refining the type descriptions during runtime.

Since:

2.6.1

registerServiceResponseListener

public AMETASMessageMask registerServiceResponseListener(AMETASPlaceUserID idService)

Convenience method to simplify event registration. This method register the caller as a listener for messages which are sent by services to it. A message mask will be created which only allows SERVICE messages to pass through, and which are addressed for this Place User. This mask is then used for the call to registerEventListener.

Since version 2.6.0, the message event registration is notify-only, i.e. the Place User must explicitely retrieve the messages after being notified.

Parameters:

idService - ID of a service.

Returns:

Mask which was used for listener registration.

requestService_WaitAndUnregister

public void requestService_WaitAndUnregister(AMETASPlaceUserID idService,
                                             java.lang.Object[] aobjParams,
                                             AMETASMessageMask mesmServiceResponse,
                                             long nWaitTime)
                                      throws NotRegisteredException,
                                             EventParameterException,
                                             TimeoutException

Convenience method for service access. This method abbreviates three steps of service usage.

At first, the idService and aobjParam parameters are used to formulate a service REQUEST message. This message is then submitted.

Then the driver is suspended using idle for the given wait time.

In the meantime, the reply should arrive via notifyListener. From there the driver must be waked up using wakeup. The now reactivated driver unregisters the Place User using the given mask, and the method returns. The driver must now retrieve the message if the message is not contained in the message event. Keep in mind that it is not recommended to automatically retrieve messages by events.

Try to avoid situations where wakeup calls may be lost; e.g. when using multithreaded Place Users. In this case you should not use this method.

Parameters:

idService - ID of the service to send the message to.

aobjParams - Parameters for the service usage. Will become the body of the request message.

mesmServiceResponse - Message mask which was used to register the Place User as a message listener.

nWaitTime - Milliseconds to wait for a reply.

Throws:

NotRegisteredException - if this Place User has not been registered as event listener before calling this method.

EventParameterException - if the parameters were invalid.

TimeoutException - if the service did not respond in the given timeout period.

requestService_WaitAndUnregister

public void requestService_WaitAndUnregister(AMETASPlaceUserID idService,
                                             java.util.Vector vctParams,
                                             AMETASMessageMask mesmServiceResponse,
                                             long nWaitTime)
                                      throws NotRegisteredException,
                                             EventParameterException,
                                             TimeoutException

Deprecated. Use the Object[] version of this method.

Convenience method for service access. This method works like the other method requestService_WaitAndUnregister except that it expects the service parameters as a vector instead of an Object array.

Parameters:

idService - ID of the service to send the message to.

vctParams - Parameters for the service usage. Will become the body of the request message.

mesmServiceResponse - Message mask which was used to register the Place User as a message listener.

nWaitTime - Milliseconds to wait for a reply.

Throws:

NotRegisteredException - if this Place User has not been registered as event listener before calling this method.

EventParameterException - if the parameters were invalid.

TimeoutException - if the service did not respond in the given timeout period.

useRequestedService

public void useRequestedService(AMETASPlaceUserID idService,
                                java.lang.Object[] aobjParams,
                                long nWaitTime)
                         throws TimeoutException

Convenience method for service access. This method first executes a registerServiceResponseListener and then a requestService_WaitAndUnregister.

Since version 2.6.0, the message event registration is notify-only, i.e. the Place User must explicitely retrieve the messages after being notified.

Parameters:

idService - ID of the service to request.

aobjParams - Parameters for the service request message.

nWaitTime - Timeout for waiting for the service reply.

Throws:

TimeoutException - if the service did not respond.

useRequestedService

public void useRequestedService(AMETASPlaceUserID idService,
                                java.util.Vector vctParams,
                                long nWaitTime)
                         throws TimeoutException

Deprecated. Use the Object[] version

Convenience method for service access. This method works like the other method useRequestedService but takes a vector as parameters.

Parameters:

idService - ID of the service to request.

vctParams - Parameters for the service request message.

nWaitTime - Timeout for waiting for the service reply.

Throws:

TimeoutException - if the service did not respond.

registerEventListener

public void registerEventListener(int nEventID,
                                  int nOptions,
                                  java.lang.Object[] objArgs)
                           throws UnauthorizedEventException,
                                  UnknownEventException,
                                  EventParameterException,
                                  DisabledEventException

Registers the Place User for incoming events. The priority is assumed to be NORMAL_PRIORITY.

Parameters:

nEventID - Event ID.

objArgs - Event-dependent parameters.

Throws:

UnauthorizedEventException - if the Place User does not have the permission for registering to this event.

UnknownEventException - if the event type is unknown.

EventParameterException - if the event parameter is invalid.

DisabledEventException - if the event is disabled.

See Also:

AMETASEvent

registerEventListener

public void registerEventListener(int nEventID,
                                  java.lang.Object[] objArgs)
                           throws UnauthorizedEventException,
                                  UnknownEventException,
                                  EventParameterException,
                                  DisabledEventException

Registers the Place User for incoming events. The options are assumed to be none. The priority is AMETASEvent.NORMAL_PRIORITY.

Parameters:

nEventID - Event ID.

objArgs - Event-dependent parameters.

Throws:

UnauthorizedEventException - if the Place User does not have the permission for registering to this event.

UnknownEventException - if the event type is unknown.

EventParameterException - if the event parameter is invalid.

DisabledEventException - if the event is disabled.

See Also:

AMETASEvent

registerEventListener

public void registerEventListener(int nEventID,
                                  short nMinPriority,
                                  int nOptions,
                                  java.lang.Object[] objArgs)
                           throws UnauthorizedEventException,
                                  UnknownEventException,
                                  EventParameterException,
                                  DisabledEventException

Registers the Place User for incoming events.

Parameters:

nEventID - Event ID.

nMinPriority - Minimum priority for notification.

objArgs - Event-dependent parameters.

Throws:

UnauthorizedEventException - if the Place User does not have the permission for registering to this event.

UnknownEventException - if the event type is unknown.

EventParameterException - if the event parameter is invalid.

DisabledEventException - if the event is disabled.

See Also:

AMETASEvent

unregisterEventListener

public void unregisterEventListener(int nEventID,
                                    java.lang.Object[] objArgs)
                             throws NotRegisteredException,
                                    UnknownEventException,
                                    EventParameterException

Unregisters the Place User for the specified event.

Parameters:

nEventID - Event ID.

objArgs - Event-dependent parameters.

Throws:

NotRegisteredException - if the Place User was not registered.

UnknownEventException - if the event type is unknown.

EventParameterException - if the parameters are invalid.