FileDocCategorySizeDatePackage
AppserverConnectionSource.javaAPI DocGlassfish v2 API16033Fri May 04 22:30:32 BST 2007com.sun.appserv.management.client

AppserverConnectionSource

public final class AppserverConnectionSource extends Object implements com.sun.appserv.management.client.ConnectionSource, NotificationListener
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 {@link com.sun.appserv.management.helper.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
com.sun.appserv.management.client.TrustStoreTrustManager
see
com.sun.appserv.management.client.TrustAnyTrustManager
see
com.sun.appserv.management.client.HandshakeCompletedListenerImpl
see
com.sun.appserv.management.client.TLSParams

Fields Summary
private final String
mHost
private final int
mPort
private final String
mProtocol
private final String
mUser
private final String
mPassword
private final TLSParams
mTLSParams
private final Map
mReserved
protected JMXConnector
mJMXConnector
private static final boolean
DISABLE_HANDSHAKE_COMPLETED_CHECK
FIXME FIXME FIXME This should be removed after the http connector supports the HandshakeCompletedListener
public static final String
TRUST_MANAGERS_KEY
[used internally]
public static final String
HANDSHAKE_COMPLETED_LISTENER_KEY
[used internally]
private static final String
PROTOCOL_PREFIX
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
public static final String
DEFAULT_PROTOCOL
Default protocol to the Appserver eg PROTOCOL_RMI.
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
private static final String
INTERNAL_HTTP
private static final String
INTERNAL_HTTPS
private static final String
HTTP_FACTORY_PACKAGES
Packages for http(s) JMXConnectorProvider.
public static final String
DEFAULT_TRUST_STORE_NAME
Name of the default TrustStore file, located in the client's home directory.
public static final String
DEFAULT_TRUST_STORE_PASSWORD
The default pasword for {@link #DEFAULT_TRUST_STORE_NAME}.
private static final String
APPSERVER_JNDI_NAME
Constructors Summary
public AppserverConnectionSource(String host, int port, String user, String userPassword, Map reserved)
Create a new instance using the default protocol without TLS.

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

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

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

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

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

param
protocol protocol to use eg PROTOCOL_RMI
param
host hostname or IP address
param
port port to which to connect
param
user username
param
userPassword password for specified username
param
tlsParams (may be null if TLS is not desired)
param
reserved reserved for future use
see
com.sun.appserv.management.client.TLSParams

		if ( reserved != null && reserved.keySet().size() != 0 )
		{
			throw new IllegalArgumentException( "No parameters may be passed in 'reserved' Map" );
		}
		
		if ( isSupportedProtocol( protocol ) )
		{
			mHost		= host;
			mPort		= port;
			mProtocol	= protocol;
			mUser		= user;
			mPassword	= userPassword;
			mTLSParams	= tlsParams;
			mReserved	= reserved;
		}
		else
		{
			throw new IllegalArgumentException( "unsupported protocol: " + protocol +
				", use either PROTOCOL_RMI or PROTOCOL_HTTP" );
		}
Methods Summary
private javax.management.remote.JMXConnectorcreateNew()

		final Map<String,Object>	env	= getCredentialsEnv( mUser, mPassword );
		
		// NetBeans fix; classloader must be more than system classloader
		env.put("jmx.remote.protocol.provider.class.loader",
			this.getClass().getClassLoader()); 

		final HandshakeCompletedListenerImpl	hcListener	=
			new HandshakeCompletedListenerImpl( getSuppliedHandshakeCompletedListener() );
		
		JMXServiceURL	url	= null;
		if ( mProtocol.equals( PROTOCOL_HTTP ) )
		{
			if ( useTLS() )
			{
				//env.put( TRUST_MANAGERS_KEY, getTrustManagers() );
                                final X509TrustManager[] tms = getTrustManagers();
                                if (tms != null && tms.length >= 1) {
                                    env.put( TRUST_MANAGERS_KEY, tms[0]);
                                }
				env.put( HANDSHAKE_COMPLETED_LISTENER_KEY, hcListener );
			}
			
			env.put( "com.sun.enterprise.as.http.auth", "BASIC" );
			env.put( "USER", mUser );
			env.put( "PASSWORD", mPassword );
			// so our JMXConnectorProvider may be found
			env.put( JMXConnectorFactory.PROTOCOL_PROVIDER_PACKAGES, HTTP_FACTORY_PACKAGES );
			
			final String	internalProtocol	= useTLS() ? INTERNAL_HTTPS : INTERNAL_HTTP;
			url	= new JMXServiceURL( internalProtocol, mHost, mPort);
		}
		else if ( mProtocol.equals( PROTOCOL_RMI ) )
		{
			if ( useTLS() )
			{
				// the only way we can communicate with/control the RMI stub is through
				// this special singleton class
				final AdminRMISSLClientSocketFactoryEnvImpl	rmiEnv	=
					AdminRMISSLClientSocketFactoryEnvImpl.getInstance();
				rmiEnv.setHandshakeCompletedListener( hcListener );
				rmiEnv.setTrustManagers( getTrustManagers() );
			}
			
			final String s = "service:jmx:rmi:///jndi/rmi://" +
				mHost + ":" + mPort  + APPSERVER_JNDI_NAME;
                         
			url	= new JMXServiceURL( s );
		}
		else
		{
			assert( false );
		}
		
		final JMXConnector conn	= JMXConnectorFactory.connect( url, env );
		
		/*
			If the connection was established with RMI, it could have been an insecure
			connection if a on-TLS stub was downloaded.  Verify that the
			a TLS Handshake was actually completed.
		 */
		if ( ! disableHandShakeCompletedCheck() )
		{
			if ( useTLS() && hcListener.getLastEvent() == null )
			{
				conn.close();
				throw new IOException( "Connection could not be established using TLS; server is not using TLS" );
			}
		}
		else
		{
			//warning( "HandshakeCompletedCheck is temporarily disabled for PROTOCOL_HTTP" );
			/* This has been commented out -- See CR: 6172198. HTTPS/JMX Connector Implementation
			does not have to accept HandshakeCompletedListener for 8.1*/
		}
		
		conn.addConnectionNotificationListener( this, null, conn );
		
		return( conn );
private booleandisableHandShakeCompletedCheck()


		  
	
	
		return( DISABLE_HANDSHAKE_COMPLETED_CHECK && mProtocol.equals( PROTOCOL_HTTP ) );
private java.lang.ObjectenvGet(java.lang.String key)

		return( mReserved == null ? null : mReserved.get( key ) );
private java.util.MapgetCredentialsEnv(java.lang.String user, java.lang.String password)

		final HashMap<String,Object>	env	= new HashMap<String,Object>();
			
		final String[]	credentials	= new String[] { mUser, mPassword };
		
		env.put( JMXConnector.CREDENTIALS, credentials );
		
		return( env );
public com.sun.appserv.management.DomainRootgetDomainRoot()
{@link 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.

return
a DomainRoot

		final DomainRoot    domainRoot  =
		    ProxyFactory.getInstance( this ).getDomainRoot( true );
		
		return domainRoot;
public javax.management.MBeanServerConnectiongetExistingMBeanServerConnection()

		try
		{
			return( getJMXConnector( false ).getMBeanServerConnection() );
		}
		catch( IOException e )
		{
		}
		return( null );
public javax.management.remote.JMXConnectorgetJMXConnector(boolean forceNew)
If the connection has already been created, return the existing JMXConnector unless 'forceNew' is true or the connection is currently null.

param
forceNew if a new connection should be created
return
JMXConnector

		if ( forceNew || mJMXConnector == null )
		{
			mJMXConnector	= createNew();
			getMBeanServerConnection( false );	// make sure it works...
		}
		
		return( mJMXConnector );
public javax.management.MBeanServerConnectiongetMBeanServerConnection(boolean forceNew)

return
getJMXConnector( forceNew ).getMBeanServerConnection()

		return( getJMXConnector( forceNew ).getMBeanServerConnection() );
private final javax.net.ssl.HandshakeCompletedListenergetSuppliedHandshakeCompletedListener()

		return( mTLSParams == null ? null : mTLSParams.getHandshakeCompletedListener() );
private final javax.net.ssl.X509TrustManager[]getTrustManagers()

		return( mTLSParams == null ? null : mTLSParams.getTrustManagers() );
public voidhandleNotification(javax.management.Notification notifIn, java.lang.Object handback)
Used internally as callback for {@link javax.management.NotificationListener}. DO NOT CALL THIS METHOD.

		if ( notifIn instanceof JMXConnectionNotification )
		{
			final JMXConnectionNotification	notif	= (JMXConnectionNotification)notifIn;
			
			final String	type	= notif.getType();
		
			if ( type.equals( JMXConnectionNotification.FAILED) ||
				type.equals( JMXConnectionNotification.CLOSED ) )
			{
				mJMXConnector	= null;
			}
		}
public static booleanisSupportedProtocol(java.lang.String protocol)

return
true if the specified protocol is supported.

		return(	protocol != null &&
				(
					protocol.equals( PROTOCOL_HTTP ) ||
					protocol.equals( PROTOCOL_RMI )
				)
			);
public java.lang.StringtoString()

		return( 
			"protocol=" + mProtocol + 
			", host=" + mHost + 
			", port=" + mPort + 
			", user=" + mUser +
			", useTLS={" + useTLS() + "}" +
			", mReserved=" + (mReserved == null ? "null" : MapUtil.toString( mReserved )) );
private final booleanuseTLS()

		return( mTLSParams != null  );
private voidwarning(java.lang.String msg)


		 
	    
	
		System.out.println( "\n***\nWARNING: " + msg );