com.ibm.websphere.management
Interface AdminService

public interface AdminService

The AdminService is the server-side interface to the WebSphere v5.0 administration functions. It exposes the public admin APIs to any code running in the server JVM. Many of the AdminService methods are also available from remote JVMs through use of the AdminClient interface. Other methods are only accessible from the same JVM as the AdminService instance.

To obtain a reference to the singleton AdminService instance, use the static method getAdminService() of the AdminServiceFactory class.

Many of the methods defined on the AdminService interface come from the JMX MBeanServer interface. The WebSphere AdminService extends the standard JMX MBeanServer function with distributed system support and enhanced security. The regular JMX MBeanServer is accessible in WebSphere JVMs from the getMBeanServer() method of the MBeanFactory interface.

Code that runs in the same JVM as the AdminService must also have the required Java 2 Security permissions in order to successfully invoke any of the AdminService methods. To obtain a reference to the AdminService in the first place, code must have at least the following permission:

• com.ibm.websphere.management.AdminPermission "getAdminService"

Other permissions that it may be necessary for code to be granted before it can call certain AdminService methods include:

• com.ibm.websphere.management.AdminPermission "getMBeanFactory"
• com.tivoli.jmx.MBeanServerPermission "MBeanServerFactory.*"
• com.tivoli.jmx.MBeanServerPermission "MBeanServer.*"

where the individual target names are:

    MBeanServer.addNotificationListener 
    MBeanServer.createMBean 
    MBeanServer.deserialize 
    MBeanServer.getAttribute 
    MBeanServer.getDefaultDomain 
    MBeanServer.getMBeanCount 
    MBeanServer.getMBeanInfo 
    MBeanServer.getObjectInstance 
    MBeanServer.instantiate 
    MBeanServer.invoke 
    MBeanServer.isRegistered 
    MBeanServer.queryMBeans 
    MBeanServer.queryNames 
    MBeanServer.registerMBean 
    MBeanServer.removeNotificationListener 
    MBeanServer.setAttribute 
    MBeanServer.unregisterMBean 
    MBeanServerFactory.createMBeanServer 
    MBeanServerFactory.newMBeanServer 
    MBeanServerFactory.findMBeanServer 
    MBeanServerFactory.releaseMBeanServer
 

See Also:

AdminServiceFactory, AdminClient, javax.management.MBeanServer

Method Summary

void	addNotificationListener(javax.management.ObjectName name, javax.management.NotificationListener listener, javax.management.NotificationFilter filter, java.lang.Object handback) Adds a listener to exactly one MBean.
void	addNotificationListenerExtended(javax.management.ObjectName name, javax.management.NotificationListener listener, javax.management.NotificationFilter filter, java.lang.Object handback) Adds a listener to multiple MBeans.
java.lang.Object	getAttribute(javax.management.ObjectName name, java.lang.String attribute) Gets the value of a specific attribute of a named MBean.
javax.management.AttributeList	getAttributes(javax.management.ObjectName name, java.lang.String[] attributes) Gets the values of several attributes of a named MBean.
java.lang.String	getCellName() Returns the name used to identify the current cell in which this process is configured.
java.lang.String	getDefaultDomain() Returns the default domain used for naming the MBean.
AdminClient	getDeploymentManagerAdminClient() Returns a reference to the AdminClient connection from this JVM to the Deployment Manager in a Network Deployment environment.
java.lang.String	getDomainName() Returns the DomainName String for this AdminService.
java.lang.String	getJvmType() Returns the JVM Type attribute of the server.
javax.management.ObjectName	getLocalServer() Returns the ObjectName handle to the Server MBean for this server.
java.lang.Integer	getMBeanCount() Returns the number of MBeans registered in the MBeanServer.
MBeanFactory	getMBeanFactory() Returns a reference to the singleton MBeanFactory instance for this JVM.
javax.management.MBeanInfo	getMBeanInfo(javax.management.ObjectName name) This method discovers the attributes and operations that an MBean exposes for management.
java.lang.String	getNodeName() Returns the name used to identify the current node in which this process is configured.
java.lang.String	getProcessName() Returns the name used to identify the current process.
java.lang.String	getProcessType() Returns the ProcessType attribute of the server.
java.lang.Object	invoke(javax.management.ObjectName name, java.lang.String operationName, java.lang.Object[] params, java.lang.String[] signature) Invokes an operation on an MBean.
Session	isAlive() Get the Session associated with the current AdminService.
boolean	isInstanceOf(javax.management.ObjectName name, java.lang.String className) Returns true if the MBean specified is an instance of the specified class, false otherwise.
boolean	isLocalServer(java.lang.String cellname, java.lang.String nodename, java.lang.String servername) Compares the cell, node, and server name parameters to those for the local server.
boolean	isRegistered(javax.management.ObjectName name) Checks whether an MBean, identified by its object name, is already registered with the MBean server.
java.util.Set	queryNames(javax.management.ObjectName name, javax.management.QueryExp query) Gets the names of MBeans controlled by the MBeanServer that match a supplied pattern.
javax.management.ObjectInstance	registerMBean(java.lang.Object object, javax.management.ObjectName name) Register the Object passed in as an MBean with the supplied JMX ObjectName.
void	removeNotificationListener(javax.management.ObjectName name, javax.management.NotificationListener listener) Removes a listener from exactly one MBean.
void	removeNotificationListenerExtended(javax.management.NotificationListener listener) Deprecated. as of 5.0.1, use removeNotificationListenerExtended(ObjectName,NotificationListener)
void	removeNotificationListenerExtended(javax.management.ObjectName name, javax.management.NotificationListener listener) Removes a listener from multiple MBeans.
void	setAttribute(javax.management.ObjectName name, javax.management.Attribute attribute) Sets the value of a specific attribute of a named MBean.
javax.management.AttributeList	setAttributes(javax.management.ObjectName name, javax.management.AttributeList attributes) Sets the values of several attributes of a named MBean.

Method Detail

getDeploymentManagerAdminClient

public AdminClient getDeploymentManagerAdminClient()
                                            throws AdminException

Returns a reference to the AdminClient connection from this JVM to the Deployment Manager in a Network Deployment environment. This method is only accessible from code running local to the AdminService. If this method is invoked while the Deployment Manager is not running or if the server is not part of a Network Deployment environment, an AdminException is thrown.

Returns:

the AdminClient to the Deployment Manager

See Also:

AdminClient

getMBeanFactory

public MBeanFactory getMBeanFactory()

Returns a reference to the singleton MBeanFactory instance for this JVM. This method is only accessible from code running local to the AdminService. To obtain a reference to the AdminService from the AdminServiceFactory, code must have at least the following permission:

• com.ibm.websphere.management.AdminPermission "getAdminService"

Returns:

the MBeanFactory for this JVM

See Also:

MBeanFactory

registerMBean

public javax.management.ObjectInstance registerMBean(java.lang.Object object,
                                                     javax.management.ObjectName name)
                                              throws javax.management.InstanceAlreadyExistsException,
                                                     javax.management.MBeanRegistrationException,
                                                     javax.management.NotCompliantMBeanException

Register the Object passed in as an MBean with the supplied JMX ObjectName. This method is only accessible from code running local to the AdminService.

Parameters:

object - the Object to be registered as an MBean.

name - the ObjectName to be associated with this MBean.

Returns:

the ObjectInstance for the registered MBean

Throws:

javax.management.InstanceAlreadyExistsException -

javax.management.MBeanRegistrationException -

javax.management.NotCompliantMBeanException -

See Also:

javax.management.ObjectName

getProcessName

public java.lang.String getProcessName()

Returns the name used to identify the current process. This value is assigned to the process key property in all ObjectNames for WebSphere MBeans originating from this JVM. This method is only accessible from code running local to the AdminService.

Returns:

the String containing the name of the process.

getNodeName

public java.lang.String getNodeName()

Returns the name used to identify the current node in which this process is configured. This value is assigned to the node key property in all ObjectNames for WebSphere MBeans originating from this JVM. This method is only accessible from code running local to the AdminService.

Returns:

the String containing the name of the node.

getCellName

public java.lang.String getCellName()

Returns the name used to identify the current cell in which this process is configured. This value is assigned to the cell key property in all ObjectNames for WebSphere MBeans originating from this JVM. This method is only accessible from code running local to the AdminService.

Returns:

the String containing the name of the cell.

getJvmType

public java.lang.String getJvmType()

Returns the JVM Type attribute of the server. JVM type values are defined in the AdminConstants interface. This method is only accessible from code running local to the AdminService.

Returns:

the String containing the type of the JVM.

See Also:

AdminConstants

getProcessType

public java.lang.String getProcessType()

Returns the ProcessType attribute of the server. Process type values are defined in the AdminConstants interface. This method is only accessible from code running local to the AdminService.

Returns:

the String containing the type of the Process

See Also:

AdminConstants

isLocalServer

public boolean isLocalServer(java.lang.String cellname,
                             java.lang.String nodename,
                             java.lang.String servername)

Compares the cell, node, and server name parameters to those for the local server. If all three match, the return value is true. Otherwise this method returns false. This method is only accessible from code running local to the AdminService.

Parameters:

cellname - a String value to compare against the name of the local cell.

nodename - a String value to compare against the name of the local node.

servername - a String value to compare against the name of the local server.

Returns:

a boolean indicating whether the supplied parameters identify the local server.

getLocalServer

public javax.management.ObjectName getLocalServer()

Returns the ObjectName handle to the Server MBean for this server. This method is only accessible from code running local to the AdminService.

Returns:

the ObjectName for the local Server MBean

See Also:

javax.management.ObjectName

isAlive

public Session isAlive()

Get the Session associated with the current AdminService. The session could be identified by a timestamp. Remote code can also use this method to test the connection from client to this AdminService.

Returns:

the Session object for the current AdminService.

See Also:

Session

queryNames

public java.util.Set queryNames(javax.management.ObjectName name,
                                javax.management.QueryExp query)

Gets the names of MBeans controlled by the MBeanServer that match a supplied pattern. This method enables any of the following to be obtained:

• the names of all MBeans accessible from the AdminService
• the names of a set of MBeans specified by pattern matching on the ObjectName and/or a Query expression
• a specific MBean name (equivalent to testing whether an MBean is registered).

When the object name is null or no domain and key properties are specified, all objects are selected (and filtered if a query is specified).

Returns:

the Set of ObjectNames for the MBeans that match the query.

See Also:

javax.management.ObjectName, javax.management.QueryExp

getAttribute

public 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

Gets the value of a specific attribute of a named MBean. The MBean is identified by its object name.

Parameters:

name -

attribute -

Returns:

Object

Throws:

javax.management.MBeanException -

javax.management.AttributeNotFoundException -

javax.management.InstanceNotFoundException -

javax.management.ReflectionException -

getAttributes

public javax.management.AttributeList getAttributes(javax.management.ObjectName name,
                                                    java.lang.String[] attributes)
                                             throws javax.management.InstanceNotFoundException,
                                                    javax.management.ReflectionException

Gets the values of several attributes of a named MBean. The MBean is identified by its object name. The attributes of that MBean are identified in a String array.

Returns:

the AttributeList containing the values for all attributes identified.

setAttribute

public 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

Sets the value of a specific attribute of a named MBean. The MBean is identified by its object name.

See Also:

javax.management.ObjectName, javax.management.Attribute

setAttributes

public javax.management.AttributeList setAttributes(javax.management.ObjectName name,
                                                    javax.management.AttributeList attributes)
                                             throws javax.management.InstanceNotFoundException,
                                                    javax.management.ReflectionException

Sets the values of several attributes of a named MBean. The MBean is identified by its object name.

See Also:

javax.management.ObjectName, javax.management.AttributeList

invoke

public 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

Invokes an operation on an MBean.

Parameters:

name -

operationName -

params -

signature -

Returns:

an Object that is the result of the invocation.

Throws:

javax.management.InstanceNotFoundException -

javax.management.MBeanException -

javax.management.ReflectionException -

getDefaultDomain

public java.lang.String getDefaultDomain()

Returns the default domain used for naming the MBean. The default domain name is used as the domain part in the ObjectName of MBeans if no domain is specified by the user.

Returns:

the String containing the default domain value.

getDomainName

public java.lang.String getDomainName()

Returns the DomainName String for this AdminService.

Returns:

the String containing the domain name for this AdminService.

getMBeanCount

public java.lang.Integer getMBeanCount()

Returns the number of MBeans registered in the MBeanServer.

getMBeanInfo

public javax.management.MBeanInfo getMBeanInfo(javax.management.ObjectName name)
                                        throws javax.management.InstanceNotFoundException,
                                               javax.management.IntrospectionException,
                                               javax.management.ReflectionException

This method discovers the attributes and operations that an MBean exposes for management.

Parameters:

name - the ObjectName for the MBean about which information is requested

Returns:

the MBeanInfo for the specified MBean

Throws:

javax.management.InstanceNotFoundException -

javax.management.IntrospectionException -

javax.management.ReflectionException -

isRegistered

public boolean isRegistered(javax.management.ObjectName name)

Checks whether an MBean, identified by its object name, is already registered with the MBean server.

Parameters:

name -

Returns:

boolean

isInstanceOf

public boolean isInstanceOf(javax.management.ObjectName name,
                            java.lang.String className)
                     throws javax.management.InstanceNotFoundException

Returns true if the MBean specified is an instance of the specified class, false otherwise.

Parameters:

name -

className -

Returns:

boolean

Throws:

javax.management.InstanceNotFoundException -

addNotificationListener

public void addNotificationListener(javax.management.ObjectName name,
                                    javax.management.NotificationListener listener,
                                    javax.management.NotificationFilter filter,
                                    java.lang.Object handback)
                             throws javax.management.InstanceNotFoundException

Adds a listener to exactly one MBean. Behaves identically to the JMX 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.

Parameters:

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

Throws:

javax.management.InstanceNotFoundException - the MBean name provided does not match any of the registered MBeans.

ConnectorException - a communication problem occured adding the listener

addNotificationListenerExtended

public void addNotificationListenerExtended(javax.management.ObjectName name,
                                            javax.management.NotificationListener listener,
                                            javax.management.NotificationFilter filter,
                                            java.lang.Object handback)

Adds a listener to multiple MBeans. Behaves similarly to the 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.

Parameters:

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

Throws:

ConnectorException - a communication problem occured adding the listener

removeNotificationListener

public void removeNotificationListener(javax.management.ObjectName name,
                                       javax.management.NotificationListener listener)
                                throws javax.management.InstanceNotFoundException,
                                       javax.management.ListenerNotFoundException

Removes a listener from exactly one MBean. Behaves identically to the JMX 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.

Parameters:

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

Throws:

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

public void removeNotificationListenerExtended(javax.management.NotificationListener listener)
                                        throws javax.management.ListenerNotFoundException

Deprecated. as of 5.0.1, use removeNotificationListenerExtended(ObjectName,NotificationListener)

Removes a listener multiple MBeans. This should be used to remove listeners which were added with 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.

Parameters:

listener - the listener object which will handle the notifications emitted by the registered MBean

Throws:

javax.management.ListenerNotFoundException - the listener is not registered in the MBean

ConnectorException - a communication problem occured adding the listener

removeNotificationListenerExtended

public void removeNotificationListenerExtended(javax.management.ObjectName name,
                                               javax.management.NotificationListener listener)
                                        throws javax.management.ListenerNotFoundException

Removes a listener from multiple MBeans. This should be used to remove listeners which were added with 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.

Parameters:

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

Throws:

javax.management.ListenerNotFoundException - the listener is not registered in the MBean

ConnectorException - a communication problem occured adding the listener