com.sun.appserv.management.client
Class AppserverConnectionSource

java.lang.Object
  extended by com.sun.appserv.management.client.AppserverConnectionSource
All Implemented Interfaces:
ConnectionSource, EventListener, NotificationListener

public final class AppserverConnectionSource
extends Object
implements NotificationListener, ConnectionSource

Supports connectivity to Sun Appserver 8.1 and later (not available prior to 8.1). This is the only official way to get a connection to the appserver.

Helper methods to simplify connecting are available in Connect.

If the server is running with TLS enabled, then you must use the constructor that includes TLSParams. Here is an example of how to connect using TLS:

final File trustStore   = new File( "~/.keystore" );
        final char[] trustStorePassword = "changeme".toCharArray();     // or whatever it is
final HandshakeCompletedListener listener = new HandshakeCompletedListenerImpl();
final TrustStoreTrustManager trustMgr = new TrustStoreTrustManager( trustStore, trustStorePassword);
trustMgr.setPrompt( true );

final TLSParams tlsParams = new TLSParams( new X509TrustManager[] { trustMgr }, listener );
final AppserverConnectionSource src     =
        new AppserverConnectionSource( AppserverConnectionSource.PROTOCOL_RMI,
                "localhost", 8686, "admin", "admin123",
                tlsParams,
                null );
final DomainRoot domainRoot     = src.getDomainRoot();
If security is not an issue, it is recommended to simply disable TLS on the server. However, you can also connect using TLS whereby the server certificate is blindly trusted:
final TLSParams tlsParams = new TLSParams( TrustAnyTrustManager.getInstanceArray(), null );
final AppserverConnectionSource src     =
        new AppserverConnectionSource( AppserverConnectionSource.PROTOCOL_RMI,
                "localhost", 8686, "admin", "admin123",
                tlsParams,
                null );
final DomainRoot domainRoot     = src.getDomainRoot();

See Also:
TrustStoreTrustManager, TrustAnyTrustManager, HandshakeCompletedListenerImpl, TLSParams

Field Summary
static String DEFAULT_PROTOCOL
          Default protocol to the Appserver eg PROTOCOL_RMI.
static String DEFAULT_TRUST_STORE_NAME
          Name of the default TrustStore file, located in the client's home directory.
static String DEFAULT_TRUST_STORE_PASSWORD
          The default pasword for DEFAULT_TRUST_STORE_NAME.
static String HANDSHAKE_COMPLETED_LISTENER_KEY
          [used internally]
protected  JMXConnector mJMXConnector
           
static String PROTOCOL_HTTP
          Internal unsupported protocol.
static String PROTOCOL_RMI
          RMI protocol to the Appserver.
static String TRUST_MANAGERS_KEY
          [used internally]
 
Constructor Summary
AppserverConnectionSource(String host, int port, String user, String userPassword, Map<String,String> reserved)
          Create a new instance using the default protocol without TLS.
AppserverConnectionSource(String protocol, String host, int port, String user, String userPassword, Map<String,String> reserved)
          Create a new instance connecting to the specified host/port with the specified protocol without TLS.
AppserverConnectionSource(String protocol, String host, int port, String user, String userPassword, TLSParams tlsParams, Map<String,String> reserved)
          Create a new instance which will use TLS for security if specified.
 
Method Summary
 DomainRoot getDomainRoot()
          DomainRoot will be returned.
 MBeanServerConnection getExistingMBeanServerConnection()
           
 JMXConnector getJMXConnector(boolean forceNew)
          If the connection has already been created, return the existing JMXConnector unless 'forceNew' is true or the connection is currently null.
 MBeanServerConnection getMBeanServerConnection(boolean forceNew)
          Return a valid MBeanServerConnection, making a new connection if necessary, or returning an existing one if still valid.
 void handleNotification(Notification notifIn, Object handback)
          Used internally as callback for NotificationListener.
static boolean isSupportedProtocol(String protocol)
           
 String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

mJMXConnector

protected JMXConnector mJMXConnector

TRUST_MANAGERS_KEY

public static final String TRUST_MANAGERS_KEY
[used internally]

See Also:
Constant Field Values

HANDSHAKE_COMPLETED_LISTENER_KEY

public static final String HANDSHAKE_COMPLETED_LISTENER_KEY
[used internally]

See Also:
Constant Field Values

PROTOCOL_RMI

public static final String PROTOCOL_RMI
RMI protocol to the Appserver. Do not use the literal value of this constant in your code; it is subject to change

See Also:
Constant Field Values

DEFAULT_PROTOCOL

public static final String DEFAULT_PROTOCOL
Default protocol to the Appserver eg PROTOCOL_RMI.

See Also:
Constant Field Values

PROTOCOL_HTTP

public static final String PROTOCOL_HTTP
Internal unsupported protocol. Not supported for external use. Do not use the literal value of this constant in your code; it is subject to change

See Also:
Constant Field Values

DEFAULT_TRUST_STORE_NAME

public static final String DEFAULT_TRUST_STORE_NAME
Name of the default TrustStore file, located in the client's home directory.

See Also:
Constant Field Values

DEFAULT_TRUST_STORE_PASSWORD

public static final String DEFAULT_TRUST_STORE_PASSWORD
The default pasword for DEFAULT_TRUST_STORE_NAME.

See Also:
Constant Field Values
Constructor Detail

AppserverConnectionSource

public AppserverConnectionSource(String host,
                                 int port,
                                 String user,
                                 String userPassword,
                                 Map<String,String> reserved)
Create a new instance using the default protocol without TLS.

Parameters:
host - hostname or IP address
port - port to which to connect
user - username
userPassword - password for specified username
reserved - reserved for future use

AppserverConnectionSource

public AppserverConnectionSource(String protocol,
                                 String host,
                                 int port,
                                 String user,
                                 String userPassword,
                                 Map<String,String> reserved)
Create a new instance connecting to the specified host/port with the specified protocol without TLS.

Note:The only supported protocol is PROTOCOL_RMI. Use of any other protocol is not supported and these protocols are subject to change or removal at any time.

Parameters:
protocol - protocol to use eg PROTOCOL_RMI
host - hostname or IP address
port - port to which to connect
user - username
userPassword - password for specified username
reserved - reserved for future use

AppserverConnectionSource

public AppserverConnectionSource(String protocol,
                                 String host,
                                 int port,
                                 String user,
                                 String userPassword,
                                 TLSParams tlsParams,
                                 Map<String,String> reserved)
Create a new instance which will use TLS for security if specified.

Parameters:
protocol - protocol to use eg PROTOCOL_RMI
host - hostname or IP address
port - port to which to connect
user - username
userPassword - password for specified username
tlsParams - (may be null if TLS is not desired)
reserved - reserved for future use
See Also:
TLSParams
Method Detail

isSupportedProtocol

public static boolean isSupportedProtocol(String protocol)
Returns:
true if the specified protocol is supported.

handleNotification

public void handleNotification(Notification notifIn,
                               Object handback)
Used internally as callback for NotificationListener. DO NOT CALL THIS METHOD.

Specified by:
handleNotification in interface NotificationListener

getJMXConnector

public JMXConnector getJMXConnector(boolean forceNew)
                             throws IOException
If the connection has already been created, return the existing JMXConnector unless 'forceNew' is true or the connection is currently null.

Specified by:
getJMXConnector in interface ConnectionSource
Parameters:
forceNew - if a new connection should be created
Returns:
JMXConnector
Throws:
IOException

getExistingMBeanServerConnection

public MBeanServerConnection getExistingMBeanServerConnection()
Specified by:
getExistingMBeanServerConnection in interface ConnectionSource
Returns:
existing connection, valid or not, may be null

getMBeanServerConnection

public MBeanServerConnection getMBeanServerConnection(boolean forceNew)
                                               throws IOException
Description copied from interface: ConnectionSource
Return a valid MBeanServerConnection, making a new connection if necessary, or returning an existing one if still valid. Some implementations may choose to not allow creation of a new connection (when 'forceNew' is specified).

Should not be called frequently, as the check for validity will make a remote call.

An implementation may choose to ignore the 'forceNew' parameter and always return the same connection.

Specified by:
getMBeanServerConnection in interface ConnectionSource
Parameters:
forceNew - creates a new connection instead of reusing an existing one
Returns:
getJMXConnector( forceNew ).getMBeanServerConnection()
Throws:
IOException

getDomainRoot

public DomainRoot getDomainRoot()
                         throws IOException
DomainRoot will be returned. Upon return, AMX is ready for use. If the server has just been started, there may be a slight delay until AMX is ready for use; this method returns only once AMX is ready for use.

Returns:
a DomainRoot
Throws:
IOException

toString

public String toString()
Overrides:
toString in class Object