com.sun.jdmk.comm
Class HtmlAdaptorServer

java.lang.Object
  com.sun.jdmk.comm.CommunicatorServer
      com.sun.jdmk.comm.HtmlAdaptorServer

All Implemented Interfaces:

CommunicatorServerMBean, Runnable, DynamicMBean, MBeanRegistration, NotificationBroadcaster

public class HtmlAdaptorServer
extends CommunicatorServer
implements MBeanRegistration, DynamicMBean

Acts as an HTML server which allows an HTML browser to manage all MBeans in the agent. The HTML protocol adaptor is implemented as a dynamic MBean.

To connect a browser to the agent open this page in a web browser:

http://host:port

where:

• host is the host name of the machine on which the agent is running.
• port is the port number used by the HTML server in the agent. (default: 8082)

The HTML protocol adaptor provides the following main HTML pages for managing MBeans in an agent:

• Agent View: Provides a list of object names of all the MBeans registered in the agent.
• Agent Administration: Registers and unregisters MBeans in the agent.
• MBean View: Reads and writes MBean attributes and perform operations on MBeans in the agent.

When the HTML protocol adaptor is started it creates a TCP/IP socket and listens for client connections.

The default port number of the socket is 8082. This default value can be changed by specifying a port number:

• in the object constructor
• using the setPort method before starting the adaptor

The default object name is define by com.sun.jdmk.ServiceName.DOMAIN and com.sun.jdmk.ServiceName.HTML_ADAPTOR_SERVER.

If a client tries to connect, the HtmlAdaptorServer creates a thread which receives and processes all subsequent requests from this client. The number of clients is limited by the maxActiveClientCount property. The default value of the maxActiveClientCount is 10.

When an HtmlAdaptorServer is stopped, all current HTTP connections are interrupted (some requests may be terminated abruptly), and the TCP/IP socket is closed.

The HtmlAdaptorServer can perform user authentication. The add/remove user authentication info methods can be used to manage users and their corresponding authentication information. The HTML server uses the 'Basic Authentication Scheme' (as defined in RFC 1945, section 11.1) to authenticate clients connecting to the server.

Limitations of the HTML protocol adaptor:

• The minimum value for the reload period is 5 seconds. (0 defaults to no reloading)
• Array of class are always displayed in read only mode.
• Arrays of dimension 2 and higher are not fully expanded.
• List of supported attribute types (for reading and writing):
  • boolean boolean[] Boolean Boolean[]
  • byte Byte Byte[]
  • char char[] Character Character[]
  • Date Date[] e.g. September 30, 1999 8:49:04 PM CEST
  • double double[] Double Double[]
  • float float[] Float Float[]
  • int int[] Integer Integer[]
  • long Long Long[]
  • Number
  • javax.management.ObjectName javax.management.ObjectName[]
  • short Short Short[]
  • String String[]
  • com.sun.jdmk.Enumerated: Supported for readable attributes. As com.sun.jdmk.Enumerated is an abstract class, only write-only attributes whose actual subclass is declared in the signature of its setter, can be set through the Html adaptor.
  • For unsupported readable attribute types, if not null, the toString() method is called.
  • If the getter of a readable attribute throw an exception, the thrown exception name and message are displayed, and this attribute cannot be set through the Html Adaptor even though it were a read-write attribute.
• List of supported operation and constructor parameter types:
  • boolean Boolean
  • byte Byte
  • char Character
  • Date e.g. September 30, 1999 8:49:04 PM CEST
  • double Double
  • float Float
  • int Integer
  • long Long
  • Number
  • javax.management.ObjectName
  • short Short
  • String

  Note 1: When reading a value of type Number the server tries to convert it first to an Integer, then a Long, then a Float and finally a Double, stopping at the first which succeeds.

  Note 2: Use the "Reload" button displayed in the HTML page of an MBean view rather than the reload button of the web-browser, otherwise you may invoke again the setters of all attributes if this was your last action.

Field Summary

Fields inherited from class com.sun.jdmk.comm.CommunicatorServer

HTML_TYPE, HTTP_TYPE, HTTPS_TYPE, OFFLINE, ONLINE, RMI_TYPE, SNMP_TYPE, STARTING, STOPPING

Constructor Summary

HtmlAdaptorServer()
Constructs an HtmlAdaptorServer that will use the default port (8082).

HtmlAdaptorServer(int port)
Constructs the HtmlAdaptorServer that will use the specified port.

HtmlAdaptorServer(int port, AuthInfo[] authInfoList)
Constructs the HtmlAdaptorServer that will use the specified port and user authentication information list.

Method Summary

void	addUserAuthenticationInfo(AuthInfo authinfo) Adds the authentication information of the user to be authenticated by this server.
void	createParser(String className, String parserName, String loaderName) Creates and registers in the MBeanServer the HTML parser MBean used by the HtmlAdaptorServer to parse incoming requests or build outgoing HTML pages.
protected void	doBind() Binds the HTML protocol adaptor.
protected void	doError(Exception e)
protected void	doProcess() Handles incoming requests.
protected void	doReceive() Collects incoming requests.
protected void	doUnbind() Unbinds the HTML protocol adaptor.
int	getActiveClientCount() Gets the number of clients currently being processed by this HtmlAdaptorServer.
Object	getAttribute(String attribute) Gets the value of a specific attribute of the HTML protocol adaptor.
AttributeList	getAttributes(String[] attributes) Gets the values of several attributes of the HTML server.
String	getLastConnectedClient() Gets the IP address of the last connected client.
int	getMaxActiveClientCount() Gets the maximum number of clients that this HtmlAdaptorServer can process concurrently.
MBeanInfo	getMBeanInfo() Gets the exposed attributes and actions of the HTML protocol adaptor.
ObjectName	getParser() Returns the ObjectName of the currently designated HTML parser MBean.
String	getProtocol() Returns the protocol of this HtmlAdaptorServer.
int	getServedClientCount() Gets the number of clients that have been processed by this HtmlAdaptorServer since its creation.
Object	invoke(String actionName, Object[] params, String[] signature) Invokes a specific operation on the HTML protocol adaptor.
boolean	isAuthenticationOn() Returns true if the list of users supported by this server is not empty.
void	postDeregister() Does nothing, needed for MBeanRegistration interface.
void	postRegister(Boolean registrationDone) Does nothing, needed for MBeanRegistration interface.
void	preDeregister() Interrupts all the current HTTP connections and close the TCP/IP socket.
ObjectName	preRegister(MBeanServer server, ObjectName name) Creates a TCP/IP connection to listen for client connections.
void	removeUserAuthenticationInfo(AuthInfo authinfo) Removes the authentication information of the given user from the list of users authenticated by this server.
void	resetParser() Sets the ObjectName of the Parser attribute to null
void	setAttribute(Attribute attribute) Sets the value of a specific attribute of the HTML protocol adaptor.
AttributeList	setAttributes(AttributeList attributes) Sets the values of several attributes of the HTML protocol adaptor.
void	setMaxActiveClientCount(int c) Sets the maximum number of clients this HtmlAdaptorServer can process concurrently.
void	setParser(ObjectName parser) Sets the MBean that will be used to parse the incoming HTML requests or to built the outgoing HTML pages.
void	stop() Stops the HTML protocol adaptor.

Methods inherited from class com.sun.jdmk.comm.CommunicatorServer

addNotificationListener, getHost, getMBeanServer, getNotificationInfo, getPort, getState, getStateString, isActive, removeNotificationListener, run, setMBeanServer, setPort, start, waitState

Methods inherited from class java.lang.Object

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

Constructor Detail

HtmlAdaptorServer

public HtmlAdaptorServer()

Constructs an HtmlAdaptorServer that will use the default port (8082).

The default port is defined in com.sun.jdmk.ServiceName.HTML_ADAPTOR_PORT.

HtmlAdaptorServer

public HtmlAdaptorServer(int port)

Constructs the HtmlAdaptorServer that will use the specified port.

Parameters:

port - An integer representing a valid port number.

HtmlAdaptorServer

public HtmlAdaptorServer(int port,
                         AuthInfo[] authInfoList)

Constructs the HtmlAdaptorServer that will use the specified port and user authentication information list.

Parameters:

port - An integer representing a valid port number.

authInfoList - The user authentication information list.

Method Detail

setParser

public void setParser(ObjectName parser)
               throws InstanceNotFoundException,
                      ServiceNotFoundException

Sets the MBean that will be used to parse the incoming HTML requests or to built the outgoing HTML pages. This MBean must implement HtmlParser and must already be registered in the agent's MBean server.

Parameters:

parser - the ObjectName of the HTML parser MBean.

Throws:

InstanceNotFoundException - The HTML parser does not exist in the repository.

ServiceNotFoundException - The requested service is not supported.

getParser

public ObjectName getParser()

Returns the ObjectName of the currently designated HTML parser MBean.

Returns:

The ObjectName that is the current value of the Parser attribute.

resetParser

public void resetParser()

Sets the ObjectName of the Parser attribute to null

createParser

public void createParser(String className,
                         String parserName,
                         String loaderName)
                  throws MalformedObjectNameException,
                         ReflectionException,
                         InstanceAlreadyExistsException,
                         MBeanRegistrationException,
                         MBeanException,
                         NotCompliantMBeanException,
                         InstanceNotFoundException

Creates and registers in the MBeanServer the HTML parser MBean used by the HtmlAdaptorServer to parse incoming requests or build outgoing HTML pages.

Parameters:

className - the class that contains the parsing procedures

parserName - the String used as an object name to register the parser into the MBeanServer

loaderName - the loader user to obtain the class of the parser

Throws:

MalformedObjectNameException - The string passed in the parameters does not have the right format.

ReflectionException - Wraps a ClassNotFoundException or a Exception that occurred when trying to invoke the MBean's constructor.

InstanceAlreadyExistsException - The MBean is already under the control of the MBeanServer.

MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.

MBeanException - The constructor of the MBean has thrown an exception.

InstanceNotFoundException - The specified class loader is not registered in the MBeanServer.

NotCompliantMBeanException

getLastConnectedClient

public String getLastConnectedClient()

Gets the IP address of the last connected client.

Returns:

The IP address of the last connected client or "unknown" if none.

See Also:

InetAddress

getProtocol

public String getProtocol()

Returns the protocol of this HtmlAdaptorServer.

Specified by:

getProtocol in interface CommunicatorServerMBean

Specified by:

getProtocol in class CommunicatorServer

Returns:

The string "html".

getServedClientCount

public int getServedClientCount()

Gets the number of clients that have been processed by this HtmlAdaptorServer since its creation.

Returns:

The number of clients handled by this HtmlAdaptorServer since its creation. This counter is not reset by the stop method.

getActiveClientCount

public int getActiveClientCount()

Gets the number of clients currently being processed by this HtmlAdaptorServer.

Returns:

The number of clients currently being processed by this HtmlAdaptorServer.

getMaxActiveClientCount

public int getMaxActiveClientCount()

Gets the maximum number of clients that this HtmlAdaptorServer can process concurrently.

Returns:

The maximum number of clients that this HtmlAdaptorServer can process concurrently.

setMaxActiveClientCount

public void setMaxActiveClientCount(int c)
                             throws IllegalStateException

Sets the maximum number of clients this HtmlAdaptorServer can process concurrently.

Parameters:

c - The number of clients.

Throws:

IllegalStateException - This method has been invoked while the communicator was ONLINE or STARTING.

addUserAuthenticationInfo

public void addUserAuthenticationInfo(AuthInfo authinfo)

Adds the authentication information of the user to be authenticated by this server. In order to populate the list of users supported by this server, invoke this method for each user you want to add. If the user already exists, then update his authentication information.

Parameters:

authinfo - the user authentication information.

removeUserAuthenticationInfo

public void removeUserAuthenticationInfo(AuthInfo authinfo)

Removes the authentication information of the given user from the list of users authenticated by this server.

Parameters:

authinfo - the user authentication information.

isAuthenticationOn

public boolean isAuthenticationOn()

Returns true if the list of users supported by this server is not empty.

Returns:

True, if the list of users supported by this server is not empty. False, if the list of supported users is empty so that no authentication is performed by this server.

stop

public void stop()

Stops the HTML protocol adaptor.

Has no effect if this SNMP protocol adaptor is OFFLINE or STOPPING.

Specified by:

stop in interface CommunicatorServerMBean

Overrides:

stop in class CommunicatorServer

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
                       throws Exception

Creates a TCP/IP connection to listen for client connections.

If no object name is provided, the server will use a default object name (defaultDomain:name=HtmlAdaptorServer).

Specified by:

preRegister in interface MBeanRegistration

Overrides:

preRegister in class CommunicatorServer

Parameters:

server - The MBeanServer in which the HTML protocol adaptor will be registered.

name - The object name of the HTML protocol adaptor or null to specify the default object name (defaultDomain:name=HtmlAdaptorServer).

Returns:

The name of the HTML protocol adaptor registered.

Throws:

java.langException - This exception should be caught by the MBeanServer and re-thrown as an MBeanRegistrationException.

Exception - This exception should be caught by the MBeanServer and re-thrown as an MBeanRegistrationException.

postRegister

public void postRegister(Boolean registrationDone)

Does nothing, needed for MBeanRegistration interface.

Specified by:

postRegister in interface MBeanRegistration

Overrides:

postRegister in class CommunicatorServer

Parameters:

registrationDone - Indicates whether or not the MBean has been successfully registered in the MBeanServer. The value false means that the registration phase has failed.

preDeregister

public void preDeregister()
                   throws Exception

Interrupts all the current HTTP connections and close the TCP/IP socket.

Specified by:

preDeregister in interface MBeanRegistration

Overrides:

preDeregister in class CommunicatorServer

Throws:

Exception - This exception should be caught by the MBeanServer and re-thrown as an MBeanRegistrationException.

postDeregister

public void postDeregister()

Does nothing, needed for MBeanRegistration interface.

Specified by:

postDeregister in interface MBeanRegistration

Overrides:

postDeregister in class CommunicatorServer

getMBeanInfo

public MBeanInfo getMBeanInfo()

Gets the exposed attributes and actions of the HTML protocol adaptor.

Specified by:

getMBeanInfo in interface DynamicMBean

Returns:

An instance of MBeanInfo containing all attributes and actions exposed by the HTML protocol adaptor.

getAttribute

public Object getAttribute(String attribute)
                    throws AttributeNotFoundException,
                           MBeanException,
                           ReflectionException

Gets the value of a specific attribute of the HTML protocol adaptor.

Gets the values for the following attributes of the HTML protocol adaptor:

Name	Type	Description
Active	boolean	True if the HtmlAdaptorServer is in the ONLINE state.
ActiveClientCount	int	The number of clients being processed currently by the HtmlAdaptorServer.
AuthenticationOn	boolean	True if the HtmlAdaptorServer requests authentication.
Host	java.lang.String	Hostname.
LastConnectedClient	java.lang.String	The IP address of the last connected client.
MaxActiveClientCount	int	The maximum number of clients the HtmlAdaptorServer can process concurrently.
Parser	ObjectName	ObjectName of the MBean used to customized HTML pages generated by the HtmlAdaptorServer.
Port	int	Port number used.
Protocol	java.lang.String	The communication protocol supported. (html)
ServedClientCount	int	The number of clients that have been processed by the HtmlAdaptorServer since its creation.
State	int	State of the HtmlAdaptorServer.
StateString	java.lang.String	String representation of the HtmlAdaptorServer state.

Specified by:

getAttribute in interface DynamicMBean

Parameters:

attribute - The name of the attribute to be retrieved

Returns:

The value of the specified attribute

Throws:

AttributeNotFoundException - The specified attribute does not exist or cannot be retrieved.

MBeanException - Wraps an exception thrown by the MBean's getter.

ReflectionException - Wraps an java.lang.Exception thrown while trying to invoke the getter.

getAttributes

public AttributeList getAttributes(String[] attributes)

Gets the values of several attributes of the HTML server.

For a list of possible attributes look at the method getAttribute.

Specified by:

getAttributes in interface DynamicMBean

Parameters:

attributes - Enables the values of several attributes of the Dynamic MBean.

Returns:

The list of retrieved attributes.

invoke

public Object invoke(String actionName,
                     Object[] params,
                     String[] signature)
              throws MBeanException,
                     ReflectionException

Invokes a specific operation on the HTML protocol adaptor.

Invokes the following operations of the HTML protocol adaptor:

Name

Signature

Description

resetParser

()

Remove the customization from HtmlAdaptorServer by resetting the Parser property to null.

createParser

(java.lang.String, java.lang.String, java.lang.String)

class name	java.lang.String	The Java class of HTML parser MBean.
object name	java.lang.String	The string used as an object name to register the parser into the MBeanServer.
class loader name	java.lang.String	The ObjectName of the MBean to use as class loader, if it is empty, the default agent class loader will be used by the MBeanServer.

Create and Register the HTML parser MBean in the MBeanServer and set the Parser attribute with the parser.

waitState

(int, long)

state	int	The state to wait for.
timeout	long	The maximum time to wait in milliseconds.

Waits to be notified of a specific state change in the HtmlAdaptorServer.

stop

()

Stop the HtmlAdaptorServer.

start

()

Start the HtmlAdaptorServer.

Specified by:

invoke in interface DynamicMBean

Parameters:

actionName - The name of the action to be invoked.

params - An array containing the parameters to be set when the action is invoked.

signature - An array containing the signature of the action. The class objects will be loaded through the same class loader as the one used for loading the HTML protocol adaptor.

Returns:

The result returned by the specific action.

Throws:

MBeanException - Wraps an exception thrown by the MBean's invoked method.

ReflectionException - Wraps an java.lang.Exception thrown while trying to invoke the method

setAttribute

public void setAttribute(Attribute attribute)
                  throws AttributeNotFoundException,
                         InvalidAttributeValueException,
                         MBeanException,
                         ReflectionException

Sets the value of a specific attribute of the HTML protocol adaptor.

Sets the following attributes of the HTML protocol adaptor:

Name	Type	Description
Port	int	Port number used. (NOTE: This can only be changed when the adaptor is OFFLINE)
MaxActiveClientCount	int	The maximum number of clients the HtmlAdaptorServer can process concurrently. (NOTE: This can only be changed when the adaptor is OFFLINE)
Parser	ObjectName	ObjectName of the HTML parser MBean used to customize the HTML pages generated by the HtmlAdaptorServer.

Specified by:

setAttribute in interface DynamicMBean

Parameters:

attribute - The identification of the attribute to be set and the value it is to be set to.

Throws:

AttributeNotFoundException - The specified attribute does not exist or cannot be retrieved.

InvalidAttributeValueException - The specified value is not a valid value for the attribute.

MBeanException - Wraps an exception thrown by the MBean's setter.

ReflectionException - Wraps an exception thrown while trying to invoke the MBean's setter.

setAttributes

public AttributeList setAttributes(AttributeList attributes)

Sets the values of several attributes of the HTML protocol adaptor.

For a list of possible attributes look at the method setAttribute.

Specified by:

setAttributes in interface DynamicMBean

Parameters:

attributes - A list of attributes: The identification of the attributes to be set and the values they are to be set to.

Returns:

The list of attributes that were set, with their new values.

doError

protected void doError(Exception e)
                throws CommunicationException

Specified by:

doError in class CommunicatorServer

Throws:

CommunicationException

doBind

protected void doBind()
               throws CommunicationException,
                      InterruptedException

Binds the HTML protocol adaptor.

Create a socket listener.

Specified by:

doBind in class CommunicatorServer

Throws:

CommunicationException - Communication problem while creating listener socket.

InterruptedException - Creating listener socket was interrupted.

doUnbind

protected void doUnbind()
                 throws CommunicationException,
                        InterruptedException

Unbinds the HTML protocol adaptor.

Close the socket listener.

Specified by:

doUnbind in class CommunicatorServer

Throws:

CommunicationException - Communication problem while closing listener socket.

InterruptedException - Closing listener socket was interrupted.

doReceive

protected void doReceive()
                  throws CommunicationException,
                         InterruptedException

Collects incoming requests.

Specified by:

doReceive in class CommunicatorServer

Throws:

CommunicationException - Communication problem while receiving request.

InterruptedException - Receiving request was interrupted.

doProcess

protected void doProcess()
                  throws CommunicationException,
                         InterruptedException

Handles incoming requests.

Specified by:

doProcess in class CommunicatorServer

Throws:

CommunicationException - Communication problem while processing request.

InterruptedException - Request processing was interrupted.