com.sun.jdmk.comm
Class HtmlAdaptorServer

java.lang.Object
  extended by com.sun.jdmk.comm.CommunicatorServer
      extended by 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:

where: The HTML protocol adaptor provides the following main HTML pages for managing MBeans in an 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:

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:


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:

NameTypeDescription
ActivebooleanTrue if the HtmlAdaptorServer is in the ONLINE state.
ActiveClientCountintThe number of clients being processed currently by the HtmlAdaptorServer.
AuthenticationOnbooleanTrue if the HtmlAdaptorServer requests authentication.
Hostjava.lang.StringHostname.
LastConnectedClientjava.lang.StringThe IP address of the last connected client.
MaxActiveClientCountintThe maximum number of clients the HtmlAdaptorServer can process concurrently.
ParserObjectNameObjectName of the MBean used to customized HTML pages generated by the HtmlAdaptorServer.
PortintPort number used.
Protocoljava.lang.StringThe communication protocol supported. (html)
ServedClientCountintThe number of clients that have been processed by the HtmlAdaptorServer since its creation.
StateintState of the HtmlAdaptorServer.
StateStringjava.lang.StringString 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:

NameSignatureDescription
resetParser()Remove the customization from HtmlAdaptorServer by resetting the Parser property to null.
createParser(java.lang.String, java.lang.String, java.lang.String)
class namejava.lang.StringThe Java class of HTML parser MBean.
object namejava.lang.StringThe string used as an object name to register the parser into the MBeanServer.
class loader namejava.lang.StringThe 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)
stateintThe state to wait for.
timeoutlongThe 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:

NameTypeDescription
PortintPort number used. (NOTE: This can only be changed when the adaptor is OFFLINE)
MaxActiveClientCountintThe maximum number of clients the HtmlAdaptorServer can process concurrently. (NOTE: This can only be changed when the adaptor is OFFLINE)
ParserObjectNameObjectName 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.

Open Source build 02
opendmk-1.0-b02 2007.10.01_19:17:46_MEST

Copyright 1998-2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.