Package i5.las2peer.api

Interface Context

All Known Implementing Classes:

ExecutionContext

public interface Context

Provides access to the context of the current call.

Method Summary

Modifier and Type	Method	Description
Envelope	createEnvelope(String identifier)	Creates a new envelope with the current main agent as signing agent and first reader.
Envelope	createEnvelope(String identifier, Agent using)	Creates a new envelope with the given agent as signing agent and first reader.
GroupAgent	createGroupAgent(Agent[] members)	Creates a new GroupAgent.
GroupAgent	createGroupAgent(Agent[] members, String groupName)	Creates a new GroupAgent with groupName.
UserAgent	createUserAgent(String passphrase)	Creates a new UserAgent.
Agent	fetchAgent(String agentId)	Fetches an agent from the network.
static Context	get()	Gets the current las2peer context.
static Context	getCurrent()	Gets the current las2peer context.
ExecutorService	getExecutor()	Gets the executor for this service.
Logger	getLogger(Class<?> cls)	Gets the logger for the given class.
Agent	getMainAgent()	Get the main agent of this context.
Service	getService()	Get the current service.
<T extends Service> T	getService(Class<T> serviceType)	Get the current service, avoiding casting.
ServiceAgent	getServiceAgent()	Get the current service agent responsible for executing the service.
ClassLoader	getServiceClassLoader()	Gets the class loader responsible for loading the current service.
String	getUserAgentIdentifierByEmail(String emailAddress)	Gets a UserAgent's identifier by its email address.
String	getUserAgentIdentifierByLoginName(String loginName)	Gets a UserAgent's identifier by its login name.
boolean	hasAccess(String agentId)	Checks if the main agent is able to unlock the agent agentId.
boolean	hasAccess(String agentId, Agent using)	Checks if the agent specified by using is able to unlock the agent agentId.
Serializable	invoke(ServiceNameVersion service, String method, Serializable... parameters)	Invokes the method of any other service on behalf of the main agent, thus sending the main agent as calling agent.
Serializable	invoke(String service, String method, Serializable... parameters)	Invokes the method of any other service on behalf of the main agent, thus sending the main agent as calling agent.
Serializable	invokeInternally(ServiceNameVersion service, String method, Serializable... parameters)	Invokes a service method using the agent of this service as calling agent.
Serializable	invokeInternally(String service, String method, Serializable... parameters)	Invokes a service method using the agent of this service as calling agent.
void	monitorEvent(MonitoringEvent event, String message)	Writes a log message to the l2p system using node observers.
void	monitorEvent(Object from, MonitoringEvent event, String message)	Writes a log message to the l2p system using node observers.
void	monitorEvent(Object from, MonitoringEvent event, String message, boolean includeActingUser)	Writes a log message to the l2p system using node observers.
void	monitorEvent(String message)	Writes a log message to the l2p system using node observers.
void	reclaimEnvelope(String identifier)	Reclaims the envelope using the current main agent agent.
void	reclaimEnvelope(String identifier, Agent using)	Reclaims the envelope using the specified agent.
void	registerReceiver(MessageReceiver receiver)	Deprecated.
Agent	requestAgent(String agentId)	Requests an agent from the network using the calling (main) agent.
Agent	requestAgent(String agentId, Agent using)	Fetches an agent from the network and trys to unlock it using the specified agent.
Envelope	requestEnvelope(String identifier)	Requests an envelope from the network.
Envelope	requestEnvelope(String identifier, Agent using)	Requests an envelope from the network.
void	storeAgent(Agent agent)	Stores and/or updates an agent to the network.
void	storeEnvelope(Envelope env)	Stores the envelope to the network and signs it with the current main agent.
void	storeEnvelope(Envelope env, EnvelopeCollisionHandler handler)	Stores the envelope to the network and signs it with the current main agent.
void	storeEnvelope(Envelope env, EnvelopeCollisionHandler handler, Agent using)	Stores the envelope to the network and signs it with the specified agent.
void	storeEnvelope(Envelope env, Agent using)	Stores the envelope to the network and signs it with the specified agent.

Method Details

getCurrent

static Context getCurrent()

Gets the current las2peer context.

Returns:

the current context

Throws:

IllegalStateException - called not in a las2peer execution thread

get

static Context get()

Gets the current las2peer context.

Returns:

the current context

Throws:

IllegalStateException - called not in a las2peer execution thread

getService

Service getService()

Get the current service.

Returns:

the current service

getService

<T extends Service> T getService(Class<T> serviceType)

Get the current service, avoiding casting.

Type Parameters:

T - type of the service

Parameters:

serviceType - service class

Returns:

the current service

getMainAgent

Agent getMainAgent()

Get the main agent of this context. In most cases, this is the user.

Returns:

the calling agent.

getServiceAgent

ServiceAgent getServiceAgent()

Get the current service agent responsible for executing the service.

Returns:

the executing service agent.

createUserAgent

UserAgent createUserAgent(String passphrase)
                   throws AgentOperationFailedException

Creates a new UserAgent.

Parameters:

passphrase - the passphrase to protect the newly generated agent

Returns:

A new unlocked UserAgent which is not stored to the network yet.

Throws:

AgentOperationFailedException - if an error occurred on the node.

createGroupAgent

GroupAgent createGroupAgent(Agent[] members)
                     throws AgentOperationFailedException

Creates a new GroupAgent.

Parameters:

members - Initial member list

Returns:

A new unlocked GroupAgent which is not stored to the network yet.

Throws:

AgentOperationFailedException - If an error occurred on the node.

createGroupAgent

GroupAgent createGroupAgent(Agent[] members,
 String groupName)
                     throws AgentOperationFailedException

Creates a new GroupAgent with groupName.

Parameters:

members - Initial member list

Returns:

A new unlocked GroupAgent which is not stored to the network yet.

Throws:

AgentOperationFailedException - If an error occurred on the node.

requestAgent

Agent requestAgent(String agentId,
 Agent using)
            throws AgentAccessDeniedException,
AgentNotFoundException,
AgentOperationFailedException

Fetches an agent from the network and trys to unlock it using the specified agent.

Parameters:

agentId - The id of the agent to fetch.

using - The agent used to unlock the fetched agent.

Returns:

An unlocked instance of the requested agent.

Throws:

AgentAccessDeniedException - If the given agent cannot access the fetched agent.

AgentNotFoundException - If the specified agent cannot be found.

AgentOperationFailedException - If an error occurred on the node.

requestAgent

Agent requestAgent(String agentId)
            throws AgentAccessDeniedException,
AgentNotFoundException,
AgentOperationFailedException

Requests an agent from the network using the calling (main) agent.

Parameters:

agentId - The id of the agent to fetch.

Returns:

An unlocked instance of the requested agent.

Throws:

AgentAccessDeniedException - If the main agent cannot access the fetched agent.

AgentNotFoundException - If the specified agent cannot be found.

AgentOperationFailedException - If an error occurred on the node.

fetchAgent

Agent fetchAgent(String agentId)
          throws AgentNotFoundException,
AgentOperationFailedException

Fetches an agent from the network.

Parameters:

agentId - The id of the agent to fetch.

Returns:

A probably locked instance of the specified agent.

Throws:

AgentNotFoundException - If the specified agent cannot be found.

AgentOperationFailedException - If an error occurred on the node.

storeAgent

void storeAgent(Agent agent)
         throws AgentAccessDeniedException,
AgentAlreadyExistsException,
AgentOperationFailedException,
AgentLockedException

Stores and/or updates an agent to the network. The given agent must be unlocked.

Parameters:

agent - The unlocked agent to store.

Throws:

AgentAccessDeniedException - If the agent cannot be overridden due to access restrictions. Or it is the AnonymousAgent.

AgentAlreadyExistsException - If another agent already exists (regarding some agent specific properties).

AgentOperationFailedException - If an error occurred on the node.

AgentLockedException - If the agent is locked.

hasAccess

boolean hasAccess(String agentId,
 Agent using)
           throws AgentNotFoundException,
AgentOperationFailedException

Checks if the agent specified by using is able to unlock the agent agentId. This also includes recursive unlocking.

Parameters:

agentId - The agent to be checked.

using - The agent to unlock.

Returns:

true If using is able to unlock agentId.

Throws:

AgentNotFoundException - If the agent specified by agentId does not exist.

AgentOperationFailedException - If an error occurred on the node.

hasAccess

boolean hasAccess(String agentId)
           throws AgentNotFoundException,
AgentOperationFailedException

Checks if the main agent is able to unlock the agent agentId. This also includes recursive unlocking.

Parameters:

agentId - The agent to be checked.

Returns:

true If the main agent is able to unlock the given agent.

Throws:

AgentNotFoundException - If the agent specified by agentId does not exist.

AgentOperationFailedException - If an error occurred on the node.

getUserAgentIdentifierByLoginName

String getUserAgentIdentifierByLoginName(String loginName)
                                  throws AgentNotFoundException,
AgentOperationFailedException

Gets a UserAgent's identifier by its login name.

Parameters:

loginName - The user's login name

Returns:

The identifier of the user agents.

Throws:

AgentNotFoundException - If there is no agent with the given login name.

AgentOperationFailedException - On node errors.

getUserAgentIdentifierByEmail

String getUserAgentIdentifierByEmail(String emailAddress)
                              throws AgentNotFoundException,
AgentOperationFailedException

Gets a UserAgent's identifier by its email address.

Parameters:

emailAddress - The user's email address.

Returns:

The identifier of the user agents.

Throws:

AgentNotFoundException - If there is no agent with the given email address.

AgentOperationFailedException - On node errors.

registerReceiver

@Deprecated
void registerReceiver(MessageReceiver receiver)
               throws AgentAlreadyRegisteredException,
AgentException

Deprecated.

Throws:

AgentAlreadyRegisteredException

AgentException

requestEnvelope

Envelope requestEnvelope(String identifier,
 Agent using)
                  throws EnvelopeAccessDeniedException,
EnvelopeNotFoundException,
EnvelopeOperationFailedException

Requests an envelope from the network. This means fetching and decrypting it using the specified agent.

Parameters:

identifier - Identifier of the envelope.

using - Agentu sing to open the envelope.

Returns:

An opened envelope.

Throws:

EnvelopeAccessDeniedException - If the given agent is not able to access the envelope.

EnvelopeNotFoundException - If the envelope doesn not exist.

EnvelopeOperationFailedException - If an error occurred in the node or network.

requestEnvelope

Envelope requestEnvelope(String identifier)
                  throws EnvelopeAccessDeniedException,
EnvelopeNotFoundException,
EnvelopeOperationFailedException

Requests an envelope from the network. This means fetching and decrypting it using the current main agent.

Parameters:

identifier - Identifier of the envelope.

Returns:

An opened envelope.

Throws:

EnvelopeAccessDeniedException - If the given agent is not able to access the envelope.

EnvelopeNotFoundException - If the envelope doesn not exist.

EnvelopeOperationFailedException - If an error occurred at the node or in the network.

storeEnvelope

void storeEnvelope(Envelope env,
 Agent using)
            throws EnvelopeAccessDeniedException,
EnvelopeOperationFailedException

Stores the envelope to the network and signs it with the specified agent.

Parameters:

env - The envelope to store.

using - The agent to be used to sign the envelope.

Throws:

EnvelopeAccessDeniedException - If the specified agent is not allowed to write to the envelope.

EnvelopeOperationFailedException - If an error occurred at the node or in the network.

storeEnvelope

void storeEnvelope(Envelope env)
            throws EnvelopeAccessDeniedException,
EnvelopeOperationFailedException

Stores the envelope to the network and signs it with the current main agent.

Parameters:

env - The envelope to store.

Throws:

EnvelopeAccessDeniedException - If the specified agent is not allowed to write to the envelope.

EnvelopeOperationFailedException - If an error occurred at the node or in the network.

storeEnvelope

void storeEnvelope(Envelope env,
 EnvelopeCollisionHandler handler,
 Agent using)
            throws EnvelopeAccessDeniedException,
EnvelopeOperationFailedException

Stores the envelope to the network and signs it with the specified agent.

Parameters:

env - The envelope to store.

handler - An handler to resolve storage conflict (e.g. the envelope has been updated in the meantime).

using - The agent to be used to sign the envelope (and must have signed the envelope or must have access to the signing agent if there are previous versions).

Throws:

EnvelopeAccessDeniedException - If the specified agent is not allowed to write to the envelope.

EnvelopeOperationFailedException - If an error occurred at the node or in the network.

storeEnvelope

void storeEnvelope(Envelope env,
 EnvelopeCollisionHandler handler)
            throws EnvelopeAccessDeniedException,
EnvelopeOperationFailedException

Stores the envelope to the network and signs it with the current main agent.

Parameters:

env - The envelope to store.

handler - An handler to resolve storage conflict (e.g. the envelope has been updated in the meantime).

Throws:

EnvelopeAccessDeniedException - If the specified agent is not allowed to write to the envelope.

EnvelopeOperationFailedException - If an error occurred at the node or in the network.

reclaimEnvelope

void reclaimEnvelope(String identifier,
 Agent using)
              throws EnvelopeAccessDeniedException,
EnvelopeNotFoundException,
EnvelopeOperationFailedException

Reclaims the envelope using the specified agent. A reclaim operation marks the envelope as deleted and indicates that the envelope is no longer needed anymore (e.g. can be deleted by other nodes). However, it is not guaranteed that the envelope will be deleted since the nature of a p2p network.

Parameters:

identifier - The identifier of the envelope.

using - The agent that has signed the envelope or an agent that has access to the signing agent.

Throws:

EnvelopeAccessDeniedException - If the agent has not signed the envelope.

EnvelopeNotFoundException - If the envelope does not exist.

EnvelopeOperationFailedException - If an error occurred at the node or in the network.

reclaimEnvelope

void reclaimEnvelope(String identifier)
              throws EnvelopeAccessDeniedException,
EnvelopeNotFoundException,
EnvelopeOperationFailedException

Reclaims the envelope using the current main agent agent. A reclaim operation marks the envelope as deleted and indicates that the envelope is no longer needed anymore (e.g. can be deleted by other nodes). However, it is not guaranteed that the envelope will be deleted since the nature of a p2p network.

Parameters:

identifier - The identifier of the envelope.

Throws:

EnvelopeAccessDeniedException - If the agent has not signed the envelope.

EnvelopeNotFoundException - If the envelope does not exist.

EnvelopeOperationFailedException - If an error occurred at the node or in the network.

createEnvelope

Envelope createEnvelope(String identifier,
 Agent using)
                 throws EnvelopeOperationFailedException,
EnvelopeAccessDeniedException

Creates a new envelope with the given agent as signing agent and first reader.

Parameters:

identifier - Identifier of the envelope.

using - Signing agent (owner) of the envelope.

Returns:

An envelope that is not stored to the network yet.

Throws:

EnvelopeOperationFailedException - If an error occurred at the node or in the network.

EnvelopeAccessDeniedException - If the agent is not allowed to create envelopes (e.g. the AnonymousAgent).

createEnvelope

Envelope createEnvelope(String identifier)
                 throws EnvelopeOperationFailedException,
EnvelopeAccessDeniedException

Creates a new envelope with the current main agent as signing agent and first reader.

Parameters:

identifier - Identifier of the envelope.

Returns:

An envelope that is not stored to the network yet.

Throws:

EnvelopeOperationFailedException - If an error occurred at the node or in the network.

EnvelopeAccessDeniedException - If the agent is not allowed to create envelopes (e.g. the AnonymousAgent).

invoke

Serializable invoke(String service,
 String method,
 Serializable... parameters)
             throws ServiceNotFoundException,
ServiceNotAvailableException,
InternalServiceException,
ServiceMethodNotFoundException,
ServiceInvocationFailedException,
ServiceAccessDeniedException,
ServiceNotAuthorizedException

Invokes the method of any other service on behalf of the main agent, thus sending the main agent as calling agent.

Parameters:

service - The service class. A version may be specified (for example package.serviceClass@1.0.0-1 or package.serviceClass@1.0). The core tries to find an appropriate version (version 1.0.5 matches 1.0). If no version is specified, the newest version is picked.

method - The service method.

parameters - The parameters list.

Returns:

The invocation result.

Throws:

ServiceNotFoundException - If the service is not known to the network.

ServiceNotAvailableException - If the service is temporarily not available.

InternalServiceException - If the remote service throws an exception.

ServiceMethodNotFoundException - If the service method does not exist.

ServiceInvocationFailedException - If the service invocation failed.

ServiceAccessDeniedException - If the access to the service has been denied.

ServiceNotAuthorizedException - If access to the service method requires a logged in user.

invoke

Serializable invoke(ServiceNameVersion service,
 String method,
 Serializable... parameters)
             throws ServiceNotFoundException,
ServiceNotAvailableException,
InternalServiceException,
ServiceMethodNotFoundException,
ServiceInvocationFailedException,
ServiceAccessDeniedException,
ServiceNotAuthorizedException

Invokes the method of any other service on behalf of the main agent, thus sending the main agent as calling agent.

Parameters:

service - The service class. A version may be specified (for example package.serviceClass@1.0.0-1 or package.serviceClass@1.0). The core tries to find an appropriate version (version 1.0.5 matches 1.0). If no version is specified, the newest version is picked.

method - The service method.

parameters - The parameters list.

Returns:

The invocation result.

Throws:

ServiceNotFoundException - If the service is not known to the network.

ServiceNotAvailableException - If the service is temporarily not available.

InternalServiceException - If the remote service throws an exception.

ServiceMethodNotFoundException - If the service method does not exist.

ServiceInvocationFailedException - If the service invocation failed.

ServiceAccessDeniedException - If the access to the service has been denied.

ServiceNotAuthorizedException - If access to the service method requires a logged in user.

invokeInternally

Serializable invokeInternally(String service,
 String method,
 Serializable... parameters)
                       throws ServiceNotFoundException,
ServiceNotAvailableException,
InternalServiceException,
ServiceMethodNotFoundException,
ServiceInvocationFailedException,
ServiceAccessDeniedException,
ServiceNotAuthorizedException

Invokes a service method using the agent of this service as calling agent.

Parameters:

service - The service class. A version may be specified (for example package.serviceClass@1.0.0-1 or package.serviceClass@1.0). The core tries to find an appropriate version (version 1.0.5 matches 1.0). If no version is specified, the newest version is picked.

method - The service method.

parameters - The parameters list.

Returns:

The invocation result.

Throws:

ServiceNotFoundException - If the service is not known to the network.

ServiceNotAvailableException - If the service is temporarily not available.

InternalServiceException - If the remote service throws an exception.

ServiceMethodNotFoundException - If the service method does not exist.

ServiceInvocationFailedException - If the service invocation failed.

ServiceAccessDeniedException - If the access to the service has been denied.

ServiceNotAuthorizedException - If access to the service method requires a logged in user.

invokeInternally

Serializable invokeInternally(ServiceNameVersion service,
 String method,
 Serializable... parameters)
                       throws ServiceNotFoundException,
ServiceNotAvailableException,
InternalServiceException,
ServiceMethodNotFoundException,
ServiceInvocationFailedException,
ServiceAccessDeniedException,
ServiceNotAuthorizedException

Invokes a service method using the agent of this service as calling agent.

Parameters:

service - The service class. A version may be specified (for example package.serviceClass@1.0.0-1 or package.serviceClass@1.0). The core tries to find an appropriate version (version 1.0.5 matches 1.0). If no version is specified, the newest version is picked.

method - The service method.

parameters - The parameters list.

Returns:

The invocation result.

Throws:

ServiceNotFoundException - If the service is not known to the network.

ServiceNotAvailableException - If the service is temporarily not available.

InternalServiceException - If the remote service throws an exception.

ServiceMethodNotFoundException - If the service method does not exist.

ServiceInvocationFailedException - If the service invocation failed.

ServiceAccessDeniedException - If the access to the service has been denied.

ServiceNotAuthorizedException - If access to the service method requires a logged in user.

getExecutor

ExecutorService getExecutor()

Gets the executor for this service. Async tasks should be handeld using this executor. They can access the current context.

Returns:

The executor responsible for the current service call.

getLogger

Logger getLogger(Class<?> cls)

Gets the logger for the given class.

Parameters:

cls - A class.

Returns:

The logging instance for the current service.

monitorEvent

void monitorEvent(String message)

Writes a log message to the l2p system using node observers. Also makes data available to MobSOS. Does not include the current acting main agent. The MonitoringEvent will default to MonitoringEvent.SERVICE_MESSAGE. Use this method for trivial log messages.

Parameters:

message - A message.

monitorEvent

void monitorEvent(MonitoringEvent event,
 String message)

Writes a log message to the l2p system using node observers. Also makes data available to MobSOS. Does not include the current acting main agent.

Parameters:

event - Differentiates between different log messages. Use MonitoringEvent.SERVICE_CUSTOM_MESSAGE_XXX as parameter.

message - A message.

monitorEvent

void monitorEvent(Object from,
 MonitoringEvent event,
 String message)

Writes a log message to the l2p system using node observers. Also makes data available to MobSOS. Does not include the current acting main agent.

Parameters:

from - Specifies from which class the message is sent from. Usually "this" is passed as parameter.

event - Differentiates between different log messages. Use MonitoringEvent.SERVICE_CUSTOM_MESSAGE_XXX as parameter.

message - A message.

monitorEvent

void monitorEvent(Object from,
 MonitoringEvent event,
 String message,
 boolean includeActingUser)

Writes a log message to the l2p system using node observers. Also makes data available to MobSOS.

Parameters:

from - Specifies from which class the message is sent from. Usually "this" is passed as parameter.

event - Differentiates between different log messages. Use MonitoringEvent.SERVICE_CUSTOM_MESSAGE_XXX as parameter.

message - A message.

includeActingUser - If set to true, the current main agent will be included.

getServiceClassLoader

ClassLoader getServiceClassLoader()

Gets the class loader responsible for loading the current service.

Returns:

The current service class loader.