com.ibm.websphere.management
Interface AdminClient
- public interface AdminClient
AdminClientImpl
is a concrete Java class to provide the client side APIs to the remote AdminService.
It delegates all the calls to the server side JMX connector through the local AdminServiceProxy. The
implemented AdminServiceProxy uses a specific transport to communication the JMX connector. The currently
supported transports include SOAP and RMI.
Most of APIs here are mapped from those defined in JMX MBeanServer interface, but not all MBeanServer APIs are contained in the AdminClientImpl.
The methods mapped from the javax.management.MBeanServer
include
- getMBeanCount()
- getDomainName()
- getDefaultDomain()
- getMBeanInfo(ObjectName)
- getAttribute(ObjectName, String)
- getAttributes(ObjectName, String[])
- setAttribute(ObjectName, Attribute attribute)
- setAttribute(ObjectName, Attribute attributeList)
- isInstanceOf(ObjectName, Class)
- isRegistered(ObjectName)
- queryNames(ObjectName, QueryExp)
- invoke(ObjectName, String, Object[], String[])
In a single-sever environment, the behavior for these methods is exactly the same as that
defined in JMX specification because there is only one MBeanServer involved. However, in a
multi-node enrivonment, it's very important to beware the existence of MBean request routing.
Most methods which take the complete javax.management.ObjectName
as a paramemter
may be routed to the downstream process if the AdminClientImpl connects to the managing process
such as the cell manager and node agent. The methods which take no parameters are only applicable
to the local MBeanServer; for example, if the getMBeanCount method is called when connected to
the cell manager, it will return only the MBean count for the cellmgr MBeanServer,
not the MBean count for the whole cell.
Routing is always in a top-down fashion; that is, from the cellmgr to the node agent to the managed process. The routing decision is based on the "node" and "process" properties in the ObjectName; the cellmgr routes requests to the downstream node agents based on the "node" property, while each node agent routes to the processes sitting in that node based on the "process" property. If the corresponding routing property is not present (for example, no "node" property when the cellmgr is determining where to route the method), the method will be executed locally.
Note that queryNames
is a little special: it accepts an ObjectName which may contain wildcard
characters (known as an ObjectName pattern). If a pattern is used and the corresponding
routing property is not found, the query will go across all downstream nodes. For example,
if the ObjectName "*:node=DefaultNode,*"
is used while connected to the cellmgr, the query
will go across all managed processes which are in the DefaultNode. A special case of this
is queryNames(null, null)
, which will allow the query to run on all downstream
processes (the same as the pattern "*:*"
). Note that if an ObjectName pattern is not
given, the query will not be routed if the routing properties are not present, like other
methods.
For the JMX event support, AdminClientImpl supports the distributed event notification which is
not specified in the current JMX specification. The semantics here is slightly different from
that from the JMX MBeanServer. For details, look at the javadoc for LocalEventNotifier
.
In case that a call to the AdminClientImpl can not reach the server,
a ConnectorNotAvailabeException
is thrown and the
AdminClientImpl is marked as "down". If the server is back online later on, the
reconnect
method can be called to bring the AdminClientImpl back "up".
Enable security in the base server.
For SOAP based AdminClient, the users need to specifiy the "username" and "password" and explicitly set "securityEnabled" as "true". Some other properties may also be required in order to make a SSL connection, these properties can be either specified as a Java system properties or passed as paramemters when invoking AdminClientFactory.createAdminClient(Properties). These properties include
- javax.net.ssl.trustStore
- javax.net.ssl.keyStore
- javax.net.ssl.trustStorePassword
- javax.net.ssl.keyStorePassword
An exmample to make a secure SOAP based AdminClient:
Properties props = new Properties(); props.setProperty(AdminClient.CONNECTOR_HOST, "localhost"); props.setProperty(AdminClient.CONNECTOR_PORT, "8880"); props.setProperty(AdminClient.CONNECTOR_TYPE, AdminClient.CONNECTOR_TYPE_SOAP); props.setProperty(AdminClient.CONNECTOR_SECURITY_ENABLED, "true"); props.setProperty(AdminClient.USERNAME, "test2"); props.setProperty(AdminClient.PASSWORD, "user24test"); props.setProperty(AdminClient.CACHE_DISABLED, "false"); props.setProperty("javax.net.ssl.trustStore", "C:/WebSphere/AppServer/etc/DummyClientTrustFile.jks"); props.setProperty("javax.net.ssl.keyStore", "C:/WebSphere/AppServer/etc/DummyClientKeyFile.jks"); props.setProperty("javax.net.ssl.trustStorePassword", "WebAS"); props.setProperty("javax.net.ssl.keyStorePassword", "WebAS"); AdminClient client = AdminClientFactory.createAdminClient(props);
To make a secure RMI based AdminClient is a little easier because you can rely on existing "com.ibm.CORBA.ConfigURL" which normal points to a property file, for instance, $WAS_ROOT/properties/sas.client.properites. There are a couple different ways to specify the login username and password and it's determined by "com.ibm.CORBA.loginSource" in "com.ibm.CORBA.ConfigURL". For programmatic login, you can set "com.ibm.CORBA.loginSource" as "none" and then provide your username/password when you create a AdminClient using AdminClientFactory.
For example,
Properties props = new Properties(); props.setProperty(AdminClient.CONNECTOR_HOST, "localhost"); props.setProperty(AdminClient.CONNECTOR_PORT, "2809"); props.setProperty(AdminClient.CONNECTOR_TYPE, AdminClient.CONNECTOR_TYPE_RMI); props.setProperty(AdminClient.CONNECTOR_SECURITY_ENABLED, "true"); props.setProperty(AdminClient.USERNAME, "test"); props.setProperty(AdminClient.PASSWORD, "user4test"); AdminClient client = AdminClientFactory.createAdminClient(props);
Field Summary
Modifier and Type | Field and Description |
---|---|
|
AUTH_TARGET
|
|
CACHE_DISABLED
To indicate that caching is enabled
|
|
CONNECTOR_AUTO_ACCEPT_SIGNER
To indicate if the connection will be established while trusting the
server signer.
|
|
CONNECTOR_HOST
The name of the property which defines the host name with which the
connector is communicating.
|
|
CONNECTOR_IPC_CONFIG
The property name for IPC ConfigURL whose value should be a soap client props file.
|
|
CONNECTOR_IPC_REQUEST_TIMEOUT
The property name whose value should be the timeout for a IPC request.
|
|
CONNECTOR_PORT
The name of the property which defines the port number with which the
connector is communicating.
|
|
CONNECTOR_SECURITY_ENABLED
To indicate the SOAP connector with SSL enabled.
|
|
CONNECTOR_SOAP_CONFIG
The property name for SOAP ConfigURL whose value should be a soap client props file.
|
|
CONNECTOR_SOAP_REQUEST_TIMEOUT
The property name whose value should be the timeout for a SOAP request.
|
|
CONNECTOR_TYPE
The name of the property which defines the type of the connector.
|
|
CONNECTOR_TYPE_IPC
The connector type which communicates via IPC.
|
|
CONNECTOR_TYPE_JMS
The connector type which communicates via JMS.
|
|
CONNECTOR_TYPE_JSR160RMI
The connector type which communicates via RMI for JSR160 support.
|
|
CONNECTOR_TYPE_RMI
The connector type which communicates via RMI.
|
|
CONNECTOR_TYPE_SOAP
The connector type which communicates via SOAP.
|
|
CONNECTOR_TYPES
A list of all the valid connector types.
|
|
KRB5_CCACHE
|
|
KRB5_CONFIG
|
|
KRB5_REFRESHING_TICKET
|
|
KRB5_SERVICE
|
|
LOGINSOURCE
The username and password when security is enabled
|
|
PASSWORD
|
|
PROTOCOL_ADAPTOR_TYPE_SNMP
The protocol adaptor type which communicates via SNMP.
|
|
USE_V5_STATISTICS
Set this System property to "true" to force the AdminClient to wrap
objects which implement the new javax.management.j2ee.statistics interface
with adapters which implement the old com.ibm.websphere.management.statistics
interface.
|
|
USERNAME
|
Method Summary
Modifier and Type | Method and Description |
---|---|
|
addNotificationListener(javax.management.ObjectName name,javax.management.NotificationListener listener,javax.management.NotificationFilter filter,java.lang.Object handback)
Adds a listener to exactly one MBean.
|
|
addNotificationListener(javax.management.ObjectName name,javax.management.ObjectName listener,javax.management.NotificationFilter filter,java.lang.Object handback)
|
|
addNotificationListenerExtended(javax.management.ObjectName name,javax.management.NotificationListener listener,javax.management.NotificationFilter filter,java.lang.Object handback)
Adds a listener to multiple MBeans.
|
|
getAttribute(javax.management.ObjectName name,java.lang.String attribute)
|
|
getAttributes(javax.management.ObjectName name,java.lang.String[] attributes)
|
|
getClassLoader(javax.management.ObjectName name)
|
|
getClassLoaderFor(javax.management.ObjectName name)
|
|
getConnectorProperties()
Return a list of properties which describe the connector.
|
|
getDefaultDomain()
|
|
getDomainName()
|
|
getMBeanCount()
|
|
getMBeanInfo(javax.management.ObjectName name)
|
|
getObjectInstance(javax.management.ObjectName objectName)
|
|
getServerMBean()
Obtain the ObjectName for the MBean representing the server which this client connects to
|
|
getType()
Returns the type of connector being used by this AdminClient.
|
|
invoke(javax.management.ObjectName name,java.lang.String operationName,java.lang.Object[] params,java.lang.String[] signature)
|
isAlive()
|
|
isAlive(int timeout)
|
|
|
isInstanceOf(javax.management.ObjectName name,java.lang.String className)
|
|
isRegistered(javax.management.ObjectName name)
|
|
queryMBeans(javax.management.ObjectName name,javax.management.QueryExp query)
|
|
queryNames(javax.management.ObjectName name,javax.management.QueryExp query)
|
|
removeNotificationListener(javax.management.ObjectName name,javax.management.NotificationListener listener)
Removes a listener from exactly one MBean.
|
|
removeNotificationListener(javax.management.ObjectName name,javax.management.ObjectName listener)
|
|
removeNotificationListener(javax.management.ObjectName name,javax.management.ObjectName listener,javax.management.NotificationFilter filter,java.lang.Object handback)
|
|
removeNotificationListenerExtended(javax.management.NotificationListener listener)
Deprecated. as of 5.0.1, you should use
removeNotificationListenerExtended(ObjectName,NotificationListener)
|
|
removeNotificationListenerExtended(javax.management.ObjectName name,javax.management.NotificationListener listener)
Removes a listener from multiple MBeans.
|
|
setAttribute(javax.management.ObjectName name,javax.management.Attribute attribute)
|
|
setAttributes(javax.management.ObjectName name,javax.management.AttributeList attributes)
|
Field Detail
CONNECTOR_TYPE
- static final java.lang.String CONNECTOR_TYPE
CONNECTOR_HOST
- static final java.lang.String CONNECTOR_HOST
CONNECTOR_PORT
- static final java.lang.String CONNECTOR_PORT
CONNECTOR_TYPE_SOAP
- static final java.lang.String CONNECTOR_TYPE_SOAP
CONNECTOR_TYPE_RMI
- static final java.lang.String CONNECTOR_TYPE_RMI
CONNECTOR_TYPE_JSR160RMI
- static final java.lang.String CONNECTOR_TYPE_JSR160RMI
CONNECTOR_TYPE_IPC
- static final java.lang.String CONNECTOR_TYPE_IPC
CONNECTOR_TYPE_JMS
- static final java.lang.String CONNECTOR_TYPE_JMS
PROTOCOL_ADAPTOR_TYPE_SNMP
- static final java.lang.String PROTOCOL_ADAPTOR_TYPE_SNMP
CONNECTOR_TYPES
- static final java.lang.String[] CONNECTOR_TYPES
CONNECTOR_SOAP_CONFIG
- static final java.lang.String CONNECTOR_SOAP_CONFIG
CONNECTOR_SOAP_REQUEST_TIMEOUT
- static final java.lang.String CONNECTOR_SOAP_REQUEST_TIMEOUT
CONNECTOR_IPC_CONFIG
- static final java.lang.String CONNECTOR_IPC_CONFIG
CONNECTOR_IPC_REQUEST_TIMEOUT
- static final java.lang.String CONNECTOR_IPC_REQUEST_TIMEOUT
CONNECTOR_SECURITY_ENABLED
- static final java.lang.String CONNECTOR_SECURITY_ENABLED
With SSL enabled, there are additional properties such as "javax.net.ssl.trustStore", "javax.net.ssl.keyStore". If the trustStore or keyStore is password protected, then "javax.net.ssl.trustStorePassword" or "javax.net.ssl.keyStorePassword" should be specified. These properties can either be specified as system properties using java -D options or passed when calling the AdminClientFactory to create the SOAP AdminClient.
LOGINSOURCE
- static final java.lang.String LOGINSOURCE
USERNAME
- static final java.lang.String USERNAME
PASSWORD
- static final java.lang.String PASSWORD
AUTH_TARGET
- static final java.lang.String AUTH_TARGET
KRB5_CCACHE
- static final java.lang.String KRB5_CCACHE
KRB5_CONFIG
- static final java.lang.String KRB5_CONFIG
KRB5_SERVICE
- static final java.lang.String KRB5_SERVICE
KRB5_REFRESHING_TICKET
- static final java.lang.String KRB5_REFRESHING_TICKET
CACHE_DISABLED
- static final java.lang.String CACHE_DISABLED
CONNECTOR_AUTO_ACCEPT_SIGNER
- static final java.lang.String CONNECTOR_AUTO_ACCEPT_SIGNER
USE_V5_STATISTICS
- static final java.lang.String USE_V5_STATISTICS
Method Detail
getType
- java.lang.String getType()
getConnectorProperties
- java.util.Properties getConnectorProperties( )
getServerMBean
- javax.management.ObjectName getServerMBean( )
- throws ConnectorException
isAlive
- Session isAlive()
- throws ConnectorException
isAlive
- Session isAlive(int timeout)
- throws ConnectorException
queryNames
- java.util.Set queryNames(javax.management.ObjectName name,
- javax.management.QueryExp query)
- throws ConnectorException
getMBeanCount
- java.lang.Integer getMBeanCount( )
- throws ConnectorException
getDomainName
- java.lang.String getDomainName( )
- throws ConnectorException
getDefaultDomain
- java.lang.String getDefaultDomain( )
- throws ConnectorException
getMBeanInfo
- javax.management.MBeanInfo getMBeanInfo( javax.management.ObjectName name)
- throws javax.management.InstanceNotFoundException
- javax.management.IntrospectionException
- javax.management.ReflectionException
- ConnectorException
javax.management.InstanceNotFoundException
javax.management.IntrospectionException
javax.management.ReflectionException
isInstanceOf
- boolean isInstanceOf(javax.management.ObjectName name,
- java.lang.String className)
- throws javax.management.InstanceNotFoundException
- ConnectorException
isRegistered
- boolean isRegistered(javax.management.ObjectName name)
- throws ConnectorException
getAttribute
- java.lang.Object getAttribute(javax.management.ObjectName name,
- java.lang.String attribute)
- throws javax.management.MBeanException
- javax.management.AttributeNotFoundException
- javax.management.InstanceNotFoundException
- javax.management.ReflectionException
- ConnectorException
javax.management.MBeanException
javax.management.AttributeNotFoundException
javax.management.InstanceNotFoundException
javax.management.ReflectionException
getAttributes
- javax.management.AttributeList getAttributes( javax.management.ObjectName name,
- java.lang.String[] attributes)
- throws javax.management.InstanceNotFoundException
- javax.management.ReflectionException
- ConnectorException
javax.management.InstanceNotFoundException
javax.management.ReflectionException
setAttribute
- void setAttribute(javax.management.ObjectName name,
- javax.management.Attribute attribute)
- throws javax.management.InstanceNotFoundException
- javax.management.AttributeNotFoundException
- javax.management.InvalidAttributeValueException
- javax.management.MBeanException
- javax.management.ReflectionException
- ConnectorException
javax.management.InstanceNotFoundException
javax.management.AttributeNotFoundException
javax.management.InvalidAttributeValueException
javax.management.MBeanException
javax.management.ReflectionException
setAttributes
- javax.management.AttributeList setAttributes( javax.management.ObjectName name,
- javax.management.AttributeList attributes)
- throws javax.management.InstanceNotFoundException
- javax.management.ReflectionException
- ConnectorException
javax.management.InstanceNotFoundException
javax.management.ReflectionException
invoke
- java.lang.Object invoke(javax.management.ObjectName name,
- java.lang.String operationName,
- java.lang.Object[] params,
- java.lang.String[] signature)
- throws javax.management.InstanceNotFoundException
- javax.management.MBeanException
- javax.management.ReflectionException
- ConnectorException
javax.management.InstanceNotFoundException
javax.management.MBeanException
javax.management.ReflectionException
addNotificationListener
- void addNotificationListener(javax.management.ObjectName name,
- javax.management.NotificationListener listener,
- javax.management.NotificationFilter filter,
- java.lang.Object handback)
- throws javax.management.InstanceNotFoundException
- ConnectorException
MBeanServer.addNotificationListener
, except that it works
in a distributed environment. This means that MBeans which are not located on
this specific process may have listeners added to it assuming routing
information is correct.
name
- the name of the MBean on which the listener should be added. listener
- the listener object which will handle the notifications emitted
by the registered MBean filter
- the filter object; if filter is null, no filtering will be
performed before handling notifications handback
- the context to be sent to the listener when a notification is
emitted javax.management.InstanceNotFoundException
- the MBean name provided does not match any
of the registered MBeans. ConnectorException
- a communication problem occured adding the
listener addNotificationListenerExtended
- void addNotificationListenerExtended( javax.management.ObjectName name,
- javax.management.NotificationListener listener,
- javax.management.NotificationFilter filter,
- java.lang.Object handback)
- throws ConnectorException
addNotificationListener(javax.management.ObjectName, javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)
method, except for the following:
- The name parameter may include wildcards, and pattern matching
is performed as in the
queryMBeans
method; null is not allowed - Listeners added with this method will receive notifications by MBeans registered in the future; i.e. the MBean does not need to be active currently to listen to it.
- An InstanceNotFoundException is never thrown.
name
- a pattern matching zero or more MBeans; notifications from all these
MBeans will be routed to the listener listener
- the listener object which will handle the notifications emitted
by the registered MBean filter
- the filter object; if filter is null, no filtering will be
performed before handling notifications handback
- the context to be sent to the listener when a notification is
emitted ConnectorException
- a communication problem occured adding the
listener removeNotificationListener
- void removeNotificationListener( javax.management.ObjectName name,
- javax.management.NotificationListener listener)
- throws javax.management.InstanceNotFoundException
- javax.management.ListenerNotFoundException
- ConnectorException
MBeanServer.removeNotificationListener
, except that it works
in a distributed environment. This means that MBeans which are not located on
this specific process may have listeners added to it assuming routing
information is correct.
This method should not be used to remove listeners added with
addNotificationListenerExtended(javax.management.ObjectName, javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)
; use
removeNotificationListenerExtended(ObjectName,NotificationListener)
instead.
name
- the name of the MBean on which the listener should be removed listener
- the listener object which will handle the notifications emitted
by the registered MBean javax.management.InstanceNotFoundException
- the MBean name provided does not match any
of the registered MBeans javax.management.ListenerNotFoundException
- the listener is not registered in the MBean ConnectorException
- a communication problem occured adding the
listener removeNotificationListenerExtended
- void removeNotificationListenerExtended( javax.management.NotificationListener listener)
- throws javax.management.ListenerNotFoundException
- ConnectorException
removeNotificationListenerExtended(ObjectName,NotificationListener)
addNotificationListenerExtended(javax.management.ObjectName, javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)
.
Behaves similarly to the removeNotificationListener(javax.management.ObjectName, javax.management.NotificationListener)
method, except
for the following:
- All instances of the given listener are removed, even if it is added to multiple MBeans.
- An InstanceNotFoundException is never thrown.
listener
- the listener object which will handle the notifications emitted
by the registered MBean javax.management.ListenerNotFoundException
- the listener is not registered in the MBean ConnectorException
- a communication problem occured adding the
listener removeNotificationListenerExtended
- void removeNotificationListenerExtended( javax.management.ObjectName name,
- javax.management.NotificationListener listener)
- throws javax.management.ListenerNotFoundException
- ConnectorException
addNotificationListenerExtended(javax.management.ObjectName, javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)
.
Behaves similarly to the removeNotificationListener(javax.management.ObjectName, javax.management.NotificationListener)
method, except
for the following:
- An InstanceNotFoundException is never thrown.
name
- the name of the MBean on which the listener should be removed; this
must be the same name as that given during
addNotificationListenerExtended (cannot remove listener from subset
of MBeans) listener
- the listener object which will handle the notifications emitted
by the registered MBean javax.management.ListenerNotFoundException
- the listener is not registered in the MBean ConnectorException
- a communication problem occured adding the
listener getClassLoaderFor
- java.lang.ClassLoader getClassLoaderFor( javax.management.ObjectName name)
- throws ConnectorException
- javax.management.InstanceNotFoundException
getClassLoader
- java.lang.ClassLoader getClassLoader( javax.management.ObjectName name)
- throws ConnectorException
- javax.management.InstanceNotFoundException
queryMBeans
- java.util.Set queryMBeans(javax.management.ObjectName name,
- javax.management.QueryExp query)
- throws ConnectorException
getObjectInstance
- javax.management.ObjectInstance getObjectInstance( javax.management.ObjectName objectName)
- throws ConnectorException
- javax.management.InstanceNotFoundException
addNotificationListener
- void addNotificationListener(javax.management.ObjectName name,
- javax.management.ObjectName listener,
- javax.management.NotificationFilter filter,
- java.lang.Object handback)
- throws ConnectorException
- javax.management.InstanceNotFoundException
removeNotificationListener
- void removeNotificationListener( javax.management.ObjectName name,
- javax.management.ObjectName listener)
- throws ConnectorException
- javax.management.InstanceNotFoundException
- javax.management.ListenerNotFoundException
javax.management.InstanceNotFoundException
javax.management.ListenerNotFoundException
removeNotificationListener
- void removeNotificationListener( javax.management.ObjectName name,
- javax.management.ObjectName listener,
- javax.management.NotificationFilter filter,
- java.lang.Object handback)
- throws ConnectorException
- javax.management.InstanceNotFoundException
- javax.management.ListenerNotFoundException
javax.management.InstanceNotFoundException
javax.management.ListenerNotFoundException