Package lumis.portal.cluster

Interface IClusterManager

All Known Implementing Classes:

AbstractClusterManager, JGroupsClusterManager, SingleServerClusterManager

@StableMinor(version="17.0",
             sinceVersion="4.1")
public interface IClusterManager

Provides operations on the portal cluster.

A message may be sent by creating it using createClusterMessage(String, Serializable) and sending the IClusterMessage object returned by calling send(IClusterTransmission). When received, the message generates a ClusterMessageReceivedEvent.

A command may be sent by creating it using createClusterCommand(Runnable) and sending the IClusterCommand object returned by calling send(IClusterTransmission). When received, the command executes the corresponding Runnable code.

Either the message or the command, can be further configured before sending by using the available methods in the returned object.

Since:

4.0.0

Version:

$Revision$ $Date$

See Also:

IClusterMessage, IClusterCommand

Method Summary

Modifier and Type	Method	Description
<T extends java.io.Serializable> T	call(IClusterCommand<T> command)	Calls a cluster command execution and returns the result of the local execution.
<T extends java.io.Serializable> java.util.Map<IClusterMember,T>	callAndWaitResponses(IClusterCallable<T> command, long timeout)	Calls a cluster command execution and waits all current cluster servers to respond with their result and, then, returns an unmodifiable map having the cluster member as the key and the execution result as the value.
IClusterCommand<java.io.Serializable>	createClusterCommand(java.lang.Runnable runnable)	Deprecated. since 8.0.0 replaced by createClusterCommand(IClusterCallable).
<T extends java.io.Serializable> IClusterCommand<T>	createClusterCommand(IClusterCallable<T> callable)	Creates a cluster command instance and returns it.
IClusterMessage	createClusterMessage(java.lang.String group, java.io.Serializable data)	Creates a cluster message instance and returns it.
void	destroy()	Destroys the cluster manager.
IClusterConfig	getClusterConfig(ITransaction transaction)	Returns a persistent cluster configuration object.
IClusterMember	getLocalMember()	Returns the current cluster member object.
java.util.Collection<IClusterMember>	getMembers()	Returns a collection with information about the current members of this cluster.
void	init()	Initializes the cluster manager.
void	send(IClusterTransmission transmission)	Sends a transmission.

Method Detail

init

void init()

Initializes the cluster manager. This method should start the monitoring and connections necessary for the cluster manager to execute its communications.

destroy

void destroy()

Destroys the cluster manager. This method should close all resources used by the cluster manager.

send

void send(IClusterTransmission transmission)

Sends a transmission.

Parameters:

transmission - the transmission. It must have been created using one of the factory methods available in IClusterManager.

See Also:

createClusterCommand(IClusterCallable), createClusterMessage(String, Serializable)

call

<T extends java.io.Serializable> T call(IClusterCommand<T> command)
                                 throws java.lang.Exception

Calls a cluster command execution and returns the result of the local execution.

This method sends the command through the cluster and gives feedback on the local server execution, in the form of the return value and the raised exception.

It is important to notice that the command will be sent over the cluster despite its execution outcome.

The given command must have been created through createClusterCommand(IClusterCallable).

Parameters:

command - the command to execute through the cluster.

Returns:

the command execution outcome.

Throws:

java.lang.Exception - the exception thrown during command execution or other unknown exception.

Since:

8.0.0

callAndWaitResponses

<T extends java.io.Serializable> java.util.Map<IClusterMember,T> callAndWaitResponses(IClusterCallable<T> command,
                                                                                            long timeout)
                                                                                     throws ClusterInvocationException,
                                                                                            java.util.concurrent.TimeoutException,
                                                                                            java.lang.InterruptedException,
                                                                                            java.lang.IllegalArgumentException

Calls a cluster command execution and waits all current cluster servers to respond with their result and, then, returns an unmodifiable map having the cluster member as the key and the execution result as the value.

If some server raises an exception, a ClusterInvocationException will be raised locally on the server that called this method with all exceptions that happened in the servers as suppressed.

This method has no guarantee it will execute properly if cluster members enter or leave the cluster during its execution.

If all responses couldn't be retrieved in the given timeout, a TimeoutException will be raised.

Type Parameters:

T - the response type. it must be serializable.

Parameters:

command - the command to be invoked.

timeout - the timeout this method will wait the invoke finishes.

Returns:

a map with all responses.

Throws:

ClusterInvocationException - if some server raises an exception during the invoke.

java.util.concurrent.TimeoutException - if the timeout has been reached and not all responses were returned.

java.lang.InterruptedException - if the thread that called this method was interrupted.

java.lang.IllegalArgumentException - if the given command is null.

java.lang.IllegalArgumentException - if the given timeout is not a positive number.

Since:

12.1.0

getMembers

java.util.Collection<IClusterMember> getMembers()
                                         throws PortalException

Returns a collection with information about the current members of this cluster.

Returns:

a collection with information about the current members of this cluster.

Throws:

PortalException

Since:

4.0.11

getLocalMember

IClusterMember getLocalMember()

Returns the current cluster member object. The object returned represents the member where this method is executed on.

Returns:

this server cluster member object.

Since:

4.2.0

createClusterMessage

IClusterMessage createClusterMessage(java.lang.String group,
                                     java.io.Serializable data)

Creates a cluster message instance and returns it.

Parameters:

group - the destination group for the message.

data - the data sent in the message.

Returns:

the cluster message created.

Since:

4.1.0

See Also:

IClusterMessage

createClusterCommand

@Deprecated
IClusterCommand<java.io.Serializable> createClusterCommand(java.lang.Runnable runnable)

Deprecated.

since 8.0.0 replaced by createClusterCommand(IClusterCallable).

Creates a cluster command instance and returns it.

Parameters:

runnable - the runnable that contains the command's execution. It must be serializable.

Since:

4.1.0

See Also:

IClusterCommand

createClusterCommand

<T extends java.io.Serializable> IClusterCommand<T> createClusterCommand(IClusterCallable<T> callable)

Creates a cluster command instance and returns it.

Parameters:

callable - the IClusterCallable that contains the command's execution. It must be serializable.

Returns:

the created cluster command.

Since:

8.0.0

getClusterConfig

IClusterConfig getClusterConfig(ITransaction transaction)
                         throws PortalException

Returns a persistent cluster configuration object. The object contains the cluster configurations, and any changes will be applied on transaction commit.

Parameters:

transaction - the transaction for persistence access.

Returns:

a persistent cluster configuration instance.

Throws:

PortalException

Since:

4.1.0