com.prosyst.mprm.rac

Class RemoteAccessClient

java.lang.Object

com.prosyst.mprm.rac.RemoteAccessClient

public abstract class RemoteAccessClient
extends java.lang.Object

Provides external system and applications with methods for remote access to mPRM services. This class can be used by stand-alone Java applications, applications deployed on J2EE application servers, plugins for the Management Console, etc. Standalone applications obtains RemoteAccessClient reference by invoking one of the static connect methods defined by this close. Note that RemoteAccessClient class cannot be instantiate directly since it is an abstract class. Applications running as a plugins for the Management Console do not need to invoke connect methods, because RemoteAccessClient is registered as service after the user logins to the mPRM Control Center or Remore Access Server. J2EE applications obtains RemoteAccessClient using the JCA mechanism, provided by the mPRM Recource adapter. A instance of a RemoteAccessClient also encaplsulates one session between the user specified in the connect to the mPRM and is subject to restrictions according to the user access rights according to its roles.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CONNECT_TO_CC Specifies the name of the optional connection parameter, which can be supplied through the params argument of the connect(java.lang.String, java.lang.String, java.util.Dictionary, java.util.Dictionary) method.
static java.lang.String	DO_NOT_RECONNECT Specifies the name of the optional connection parameter, which can be supplied through the params argument of the connect(java.lang.String, java.lang.String, java.util.Dictionary, java.util.Dictionary) method.
static java.lang.String	EVENTS_REMOTE_RAS_ONLY Specifies the name of the optional event registration parameter, which can be supplied through the properties argument of the addEventListener(java.lang.String, java.util.Dictionary, com.prosyst.mprm.backend.event.EventListener) method.
protected static com.prosyst.mprm.rac.spi.RemoteAccessClientFactory	factory
static java.lang.String	HOSTNAME_VERIFIER Property name for a hostname verifier associated to the connection, which must be used as a key in the params parameter of the connect(java.lang.String, java.lang.String, java.util.Dictionary, java.util.Dictionary) method.
static java.lang.String	KEY_MANAGER Property name for a key manager associated to the connection, which must be used as a key in the params parameter of the connect(java.lang.String, java.lang.String, java.util.Dictionary, java.util.Dictionary) method.
static java.lang.String	SSL_SERVER_SOCKET_FACTORY Property name for a SSLServerSocketFactory that should be used to open SSL connection (of SSL/HTTPS is used as underlying transport), which must be used as a key in the params parameter of the connect(java.lang.String, java.lang.String, java.util.Dictionary, java.util.Dictionary) method.
static java.lang.String	SSL_SOCKET_FACTORY Property name for a SSLSocketFactory that should be used to open SSL connection (of SSL/HTTPS is used as underlying transport), which must be used as a key in the params parameter of the connect(java.lang.String, java.lang.String, java.util.Dictionary, java.util.Dictionary) method.
static java.lang.String	TRUST_MANAGER Property name for a trust manager associated to the connection, which must be used as a key in the params parameter of the connect(java.lang.String, java.lang.String, java.util.Dictionary, java.util.Dictionary) method.
static java.lang.String	USER_PASSWORD Property name for the password based autentication, which must be used as a key in the credentials parameter of the connect(java.lang.String, java.lang.String, java.util.Dictionary, java.util.Dictionary) method.

Constructor Summary

Constructors

Constructor and Description
RemoteAccessClient()

Method Summary

Modifier and Type	Method and Description
abstract void	addConnectionListener(ConnectionListener listener) Adds a connection listener instance which will be notified if the connection state of the session represented by this Remote Access Cliens changes.
abstract void	addEventListener(java.lang.String type, java.util.Dictionary properties, EventListener listener) Registers listener which will be notified when a event of the supplied type has been fire on the mPRM backend hosts and corresponds to the supplied filtering properties.
abstract void	addEventListener(java.lang.String type, EventListener listener) Registers listener which will be notified when a event of the supplied type has been fire on any of the mPRM backend hosts.
abstract void	close() Closes the mPRM session represented by this Remote Access Client instance.
static RemoteAccessClient	connect(P2PConnection connection, java.lang.String userName, java.util.Dictionary credentials, java.util.Dictionary params) Creates a user session over an already existing network connection with a remote mPRM server.
static RemoteAccessClient	connect(java.lang.String[] urls, java.lang.String userName, java.util.Dictionary credentials, java.util.Dictionary params) Similar as connect(java.lang.String, java.lang.String, java.util.Dictionary, java.util.Dictionary), but allows supplying of more then one URL-s, which will be used sequentialy until connection with some of them is successfuly established.
static RemoteAccessClient	connect(java.lang.String url, java.lang.String userName, java.util.Dictionary credentials, java.util.Dictionary params) Makes network connection with the mPRM Server (CC or RAS) with the supplied url and performs authentication of the user specified by the supplied userName and credentials.
abstract NetService	getNetService(java.lang.String netServiceName) Returns the NetService instance representing the net service with the given name registered on the remote host (RAS or CC) which this Remote Access Client is connected to.
abstract RemoteReference	getRemoteReference(java.lang.String serviceClassName, java.lang.Class clientClass) Returns remote reference to the OSGi service registered at the RAS or CC which this Remote Access Client is connected to.
abstract RemoteReference	getRemoteReference(java.lang.String serviceClassName, java.lang.String filter, java.lang.Class clientClass) This method is similar to getRemoteReference(java.lang.String, java.lang.Class), but in addition it supports supplying of the service filter.
abstract java.lang.Object	getService(java.lang.String serviceClassName) Returns instance of mPRM service object with the supplied service class name.
abstract java.lang.String	getUserName() Returns the name of the user which has open the session represented by this Remote Access Client instance.
abstract boolean	isConnected() Returns if the session represented by this Remote Access Server is closed.
abstract boolean	isConnectedToControlCenter() Returns whether the Remote Access Client is connected to the mPRM Control Center.
abstract void	removeConnectionListener(ConnectionListener listener) Removes the supplied listener from the list of registired connection listeners.
abstract void	removeEventListener(java.lang.String type, EventListener listener) Removes listener registered for the events of the supplied type.
abstract void	switchToControlCenter() Reconnects the Remote Access Server to the mPRM Control Center.

Methods inherited from class java.lang.Object

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

Field Detail

USER_PASSWORD

public static final java.lang.String USER_PASSWORD

Property name for the password based autentication, which must be used as a key in the credentials parameter of the connect(java.lang.String, java.lang.String, java.util.Dictionary, java.util.Dictionary) method.

See Also:

Constant Field Values

CONNECT_TO_CC

public static final java.lang.String CONNECT_TO_CC

Specifies the name of the optional connection parameter, which can be supplied through the params argument of the connect(java.lang.String, java.lang.String, java.util.Dictionary, java.util.Dictionary) method. Passing CONNECT_TO_CC with value "true" forses the Remote Access Client to establish the connection with the Control Center of the mPRM System. This should be used for system configuration purposes.

See Also:

Constant Field Values

DO_NOT_RECONNECT

public static final java.lang.String DO_NOT_RECONNECT

Specifies the name of the optional connection parameter, which can be supplied through the params argument of the connect(java.lang.String, java.lang.String, java.util.Dictionary, java.util.Dictionary) method. Passing DO_NOT_RECONNECT with value "true" instructs the Remote Access Client that it should not be redirected during the connection establishment. Recconnection could occur as a result of the load balancing mechanishms.

See Also:

Constant Field Values

EVENTS_REMOTE_RAS_ONLY

public static final java.lang.String EVENTS_REMOTE_RAS_ONLY

Specifies the name of the optional event registration parameter, which can be supplied through the properties argument of the addEventListener(java.lang.String, java.util.Dictionary, com.prosyst.mprm.backend.event.EventListener) method. Passing EVENTS_REMOTE_RAS_ONLY with value "true" instructs the Event Service that this listener should receive only events originating from the Remote Access Server (or Control Center), which this Remote Access Client is connected to.

See Also:

Constant Field Values

KEY_MANAGER

public static final java.lang.String KEY_MANAGER

Property name for a key manager associated to the connection, which must be used as a key in the params parameter of the connect(java.lang.String, java.lang.String, java.util.Dictionary, java.util.Dictionary) method. Its value must be instance of javax.net.ssl.KeyManager

See Also:

Constant Field Values

TRUST_MANAGER

public static final java.lang.String TRUST_MANAGER

Property name for a trust manager associated to the connection, which must be used as a key in the params parameter of the connect(java.lang.String, java.lang.String, java.util.Dictionary, java.util.Dictionary) method. Its value must be instance of javax.net.ssl.TrustManager

See Also:

Constant Field Values

HOSTNAME_VERIFIER

public static final java.lang.String HOSTNAME_VERIFIER

Property name for a hostname verifier associated to the connection, which must be used as a key in the params parameter of the connect(java.lang.String, java.lang.String, java.util.Dictionary, java.util.Dictionary) method. Its value must be instance of javax.net.ssl.HostnameVerifier

See Also:

Constant Field Values

SSL_SOCKET_FACTORY

public static final java.lang.String SSL_SOCKET_FACTORY

Property name for a SSLSocketFactory that should be used to open SSL connection (of SSL/HTTPS is used as underlying transport), which must be used as a key in the params parameter of the connect(java.lang.String, java.lang.String, java.util.Dictionary, java.util.Dictionary) method. Its value must be instance of javax.net.ssl.SSLSocketFactory

See Also:

Constant Field Values

SSL_SERVER_SOCKET_FACTORY

public static final java.lang.String SSL_SERVER_SOCKET_FACTORY

Property name for a SSLServerSocketFactory that should be used to open SSL connection (of SSL/HTTPS is used as underlying transport), which must be used as a key in the params parameter of the connect(java.lang.String, java.lang.String, java.util.Dictionary, java.util.Dictionary) method. Its value must be instance of javax.net.ssl.SSLServerSocketFactory

See Also:

Constant Field Values

factory

protected static com.prosyst.mprm.rac.spi.RemoteAccessClientFactory factory

Constructor Detail

RemoteAccessClient

public RemoteAccessClient()

Method Detail

connect

public static RemoteAccessClient connect(java.lang.String url,
                                         java.lang.String userName,
                                         java.util.Dictionary credentials,
                                         java.util.Dictionary params)
                                  throws ManagementException

Makes network connection with the mPRM Server (CC or RAS) with the supplied url and performs authentication of the user specified by the supplied userName and credentials. If previous steps finish successfuly the method returns RemoteAccessClient instance which represents the session of the user with the mPRM and provides methods for using mPRM services.

Parameters:

url - represents the protocol and address of the remote mPRM server (CC or RAS). For example socket://mprm.acme.com:11449.

userName - the name of the mPRM user.

credentials - the credentials used for authentication of the user. The content of this dictionary must conform to the used authentication mechanism. For password based authentication this dictionary must contains {"userPassword", }.

params - additional connection establishment parameters. Can be null.

Returns:

RemoteAccessClient instance.

Throws:

ManagementException - if connection cannot be open or the supplied user account is incorrect.

connect

public static RemoteAccessClient connect(java.lang.String[] urls,
                                         java.lang.String userName,
                                         java.util.Dictionary credentials,
                                         java.util.Dictionary params)
                                  throws ManagementException

Similar as connect(java.lang.String, java.lang.String, java.util.Dictionary, java.util.Dictionary), but allows supplying of more then one URL-s, which will be used sequentialy until connection with some of them is successfuly established.

Parameters:

urls - represents array of urls of the remote mPRM servers (CC or/and several RAS)

userName - the name of the mPRM user.

credentials - the credentials used for authentication of the user. The content of this dictionary must conform to the used authentication mechanism. For password based authentication this dictionary must contains {"userPassword", }.

params - additional connection establishment parameters. Can be null.

Returns:

RemoteAccessClient instance.

Throws:

ManagementException - if connection cannot be open or the supplied user account is incorrect.

connect

public static RemoteAccessClient connect(P2PConnection connection,
                                         java.lang.String userName,
                                         java.util.Dictionary credentials,
                                         java.util.Dictionary params)
                                  throws ManagementException

Creates a user session over an already existing network connection with a remote mPRM server. One network connection could be used for more then one user sessions simultaneously. The performs authentication of the user specified by the supplied userName and credentials and returns RemoteAccessClient instance which represents create user session with the mPRM and provides methods for using mPRM services.

Parameters:

connection - the network connection to the mPRM Server (CC or RAS).

userName - the name of the mPRM user.

credentials - the credentials used for authentication of the user. The content of this dictionary must conform to the used authentication mechanism. For password based authentication this dictionary must contains {"userPassword", }.

params - additional connection establishment parameters. Can be null.

Returns:

RemoteAccessClient instance.

Throws:

ManagementException - if connection cannot be open or the supplied user account is incorrect.

getService

public abstract java.lang.Object getService(java.lang.String serviceClassName)
                                     throws ManagementException

Returns instance of mPRM service object with the supplied service class name. For example obtaining Log Reader service can be done as follows: LogReader logReader = (LogReader)rac.getService("com.prosyst.mprm.admin.log.LogReader");.

Parameters:

serviceClassName - the class name of the service interface.

Returns:

the service instance.

Throws:

ManagementException - if there is no such service or in case of a system level error.

getRemoteReference

public abstract RemoteReference getRemoteReference(java.lang.String serviceClassName,
                                                   java.lang.Class clientClass)
                                            throws ManagementException

Returns remote reference to the OSGi service registered at the RAS or CC which this Remote Access Client is connected to. The returned reference can be used for remote method invocation over mPower RPC service. This method returns valid reference even if the remote service is not currently available, and it could be succesfully used as soon as the service is registered.

Parameters:

serviceClassName - the service interface name as it is registered with the OSGi service registry.

clientClass - the instance which class loader will be used by the mPower RPC service to load the classes of the method return types. If this argument is null the system class loader will be used.

Returns:

mPower RPC reference instance.

Throws:

ManagementException - if a system level error occures.

getRemoteReference

public abstract RemoteReference getRemoteReference(java.lang.String serviceClassName,
                                                   java.lang.String filter,
                                                   java.lang.Class clientClass)
                                            throws ManagementException

This method is similar to getRemoteReference(java.lang.String, java.lang.Class), but in addition it supports supplying of the service filter.

Parameters:

serviceClassName - the service interface name as it is registered with the OSGi service registry.

filter - the LDAP filter for the service registration properties.

clientClass - the instance which class loader will be used by the mPower RPC service to load the classes of the method return types. If this argument is null the system class loader will be used.

Returns:

mPower RPC reference instance.

Throws:

ManagementException - if a system level error occures.

getNetService

public abstract NetService getNetService(java.lang.String netServiceName)
                                  throws ManagementException

Returns the NetService instance representing the net service with the given name registered on the remote host (RAS or CC) which this Remote Access Client is connected to. The returned instance could be used for low level network communication over mPower Connection Framework.

Parameters:

netServiceName - the name of the remote Net service.

Returns:

the NetService instance.

Throws:

ManagementException - if some communication level error has occured.

addEventListener

public abstract void addEventListener(java.lang.String type,
                                      EventListener listener)
                               throws ManagementException

Registers listener which will be notified when a event of the supplied type has been fire on any of the mPRM backend hosts. The event is distributed ovet mPower Event service.

Parameters:

type - the eventType with this listener is interested in.

listener - the event listener which will be notified by mPower Event service.

Throws:

ManagementException - if some communication level error occures furing listener registration.

addEventListener

public abstract void addEventListener(java.lang.String type,
                                      java.util.Dictionary properties,
                                      EventListener listener)
                               throws ManagementException

Registers listener which will be notified when a event of the supplied type has been fire on the mPRM backend hosts and corresponds to the supplied filtering properties. For now the only supported properties are EVENTS_REMOTE_RAS_ONLY and EventListener.EVENT_CUSTOM_FILTER.

Parameters:

type - the eventType with this listener is interested in.

properties - aditional event registration properties.

listener - the event listener which will be notified by mPower Event service.

Throws:

ManagementException - if some communication level error occures furing listener registration.

removeEventListener

public abstract void removeEventListener(java.lang.String type,
                                         EventListener listener)

Removes listener registered for the events of the supplied type. If the same listener instance is registered with other event types it will continue to receive events of thouse types.

Parameters:

type - the eventType with this listener is no longer interested in.

listener - to be unregistered.

isConnectedToControlCenter

public abstract boolean isConnectedToControlCenter()

Returns whether the Remote Access Client is connected to the mPRM Control Center.

Returns:

true if the connection is to the mPRM Control Center, false otherwise - if the RAC is connected to a Remote Access Server.

switchToControlCenter

public abstract void switchToControlCenter()
                                    throws ManagementException

Reconnects the Remote Access Server to the mPRM Control Center. If the RAC is already connected to the Control Center this method does nothing.

Throws:

ManagementException - if the Control Center is not online or if some system level error occures.

addConnectionListener

public abstract void addConnectionListener(ConnectionListener listener)

Adds a connection listener instance which will be notified if the connection state of the session represented by this Remote Access Cliens changes.

Parameters:

listener - the application implementation of the ConnectionListener interface.

See Also:

ConnectionListener.event(int eventType)

removeConnectionListener

public abstract void removeConnectionListener(ConnectionListener listener)

Removes the supplied listener from the list of registired connection listeners.

Parameters:

listener - the listener object being removed.

isConnected

public abstract boolean isConnected()

Returns if the session represented by this Remote Access Server is closed.

Returns:

true if the connection is closed, false otherwise.

close

public abstract void close()

Closes the mPRM session represented by this Remote Access Client instance.

getUserName

public abstract java.lang.String getUserName()

Returns the name of the user which has open the session represented by this Remote Access Client instance.

Returns:

the user name