org.glassfish.cafe.api
Interface UserProcedure

All Known Subinterfaces:

PresenceSource, PresenceWatcher, Registration, WatcherInfoSubscriber

public interface UserProcedure

Represents a user procedure, in which a user starts an action or discloses information to the network or to a server, with a limited validity period. User procedures have events that are related to the validity period or to the reception of requested information. User procedures also have update methods to change the validity period or the published or requested information. Registration, the publication of presence information, the subscription to presence information and subscription to subscription events on presence information are examples of a user procedure.

After creating a user procedure, normally additional information is set before starting the user procedure towards the network with the update() method. This applies especially to the expiration time. When a user procedure is created, the expiration time has a default of 3600 seconds. This period can be changed with the setExpirationTime() method.

Events (UserProcedureEvent.Type) indicating whether the procedure is accepted or not are received each time the update() method is invoked.

Users of this interface must take into account that the remote end point may reduce the expiration time. In such case, after the receipt of an acknowledgment of one of the messages caused by the invocation of the update() operation, the user is able to check what the real expiration time is using getExpirationTime(). Note that there is also an event indicating that the validity period of a user procedure is about to expire.

The state machine for UserProcedure is illustrated in the following diagram:

Author:

Mathieu Hutschemaekers

See Also:

UserProcedureEvent.Type, CommunicationSession

Nested Class Summary

static class

UserProcedure.State

Method Summary

<T> void	addAgent(String name, Agent<T> agent) Set an agent instance in the communication.
void	end() Ends the procedure.
<T> Agent<T>	getAgent(String name) Gets the agent from its name.
<T> Collection<Agent<T>>	getAgents() Retrieve the agent instance pertaining to the communication.
Date	getExpirationTime() Returns the expiration time.
UserProcedureMessage	getMessage() Returns the message in the user procedure.
UserProcedure.State	getState() Returns the current state of the procedure.
String	getUserId() Returns the user who initiated the procedure.
<T> Agent<T>	removeAgent(String name) Method to remove an agent from the communication.
void	setExpirationTime(Date expires) Sets the expiration time.
void	update() Starts the procedure or requests a refresh or update of remote data by sending a message.

Method Detail

getUserId

String getUserId()

Returns the user who initiated the procedure.

Returns:

a string containing the user's URL

update

void update()

Starts the procedure or requests a refresh or update of remote data by sending a message.

end

void end()

Ends the procedure.

getState

UserProcedure.State getState()

Returns the current state of the procedure.

Returns:

the procedure state.

getMessage

UserProcedureMessage getMessage()

Returns the message in the user procedure.

Returns:

the last received message in the conversation.

setExpirationTime

void setExpirationTime(Date expires)

Sets the expiration time.

Parameters:

expires - expiration time as absolute time.

Throws:

java.lang.InvalidArgumentException - If expiration time is not valid.

IllegalStateException - If the state is not INITIATED or ACTIVE.

getExpirationTime

Date getExpirationTime()

Returns the expiration time. If state is STARTING or REFRESHING, the expiration time returned is the same one that was set by the user of this interface. If state is ACTIVE, the value returned corresponds to the real expiration time approved by the remote end point.

Returns:

expiration time as absolute time.

addAgent

<T> void addAgent(String name,
                  Agent<T> agent)

Set an agent instance in the communication.

Type Parameters:

T - Type of Agent.

Parameters:

agent - An instance of Agent.

See Also:

Agent

getAgents

<T> Collection<Agent<T>> getAgents()

Retrieve the agent instance pertaining to the communication. This API returns only agents that are not call back agents.

Type Parameters:

T - Type of Agent being returned.

Returns:

Return the agent instance previously set or return null if the agent is not set.

getAgent

<T> Agent<T> getAgent(String name)

Gets the agent from its name.

Parameters:

name - Name of the Agent

Returns:

agent

removeAgent

<T> Agent<T> removeAgent(String name)

Method to remove an agent from the communication.

Type Parameters:

T - type

Parameters:

name - name of the agent.

Returns:

agent if it exists.