19.7. WS-CM Configuration

19.7.1. ManagedService Policy Assertion

The configuration management is configured through a policy assertion that the service is looking up from its initial configuration. The initial configuration are the Metro configuration files. In the case of a web service with bundled WSDL, the bundled WSDL is the configuration file. Otherwise Metro will look for a file in WEB-INF or META-INF named wsit-<endpoint implementation class>.xml. The configuration file is in (slightly simplified) WSDL 1.1 format. Here is how a configuration file might look like:

<?xml version='1.0' encoding='UTF-8'?>
<definitions xmlns:wsp="http://www.w3.org/ns/ws-policy"
  xmlns:wspp="http://java.sun.com/xml/ns/wsit/policy"
  xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
  xmlns:tns="http://test.ws.xml.sun.com/"
  xmlns="http://schemas.xmlsoap.org/wsdl/"
  targetNamespace="http://test.ws.xml.sun.com/"
  name="NewWebServiceService">
    <message name="echo">
        <part name="parameters" element="tns:echo" />
    </message>
    <message name="echoResponse">
        <part name="parameters" element="tns:echoResponse" />
    </message>
    <portType name="NewWebService">
        <operation name="echo">
            <input message="tns:echo" />
            <output message="tns:echoResponse" />
        </operation>
    </portType>
    <binding name="NewWebServicePortBinding" type="tns:NewWebService">
        <wsp:PolicyReference URI="#NewWebServicePortBindingPolicy"/>
        <operation name="echo"/>
    </binding>
    <service name="NewWebServiceService">
        <port name="NewWebServicePort" binding="tns:NewWebServicePortBinding">
            <wsp:Policy>
                <sunman:ManagedService xmlns:sunman="http://java.sun.com/xml/ns/metro/management" id="WebApplicationSunJAXWSFromWSDL">
                </sunman:ManagedService>
            </wsp:Policy>
        </port>
    </service>
</definitions>

The part that enables the configuration management is the policy expression under the WSDL port element. Note that this policy must be a child element of the WSDL port element. You could also use a PolicyReference instead of inlining the policy.

19.7.1.1. ManagedService ID

The id attribute of the ManagedService policy assertion is mandatory and can be anything that is convenient for the configuration management client. The ID must be unique for each web services that is managed by a management client:

<sunman:ManagedService id="user defined"/>

Note that the default implementation will write this ID to a database, i.e. it might be subject to the length restrictions of the database column. The default implementation itself does not enforce any length restrictions.

19.7.1.2. ManagedService Start

The start attribute of the ManagedService policy assertion controls the behavior of the managed web service when it is instantiated. The web service may, depending on the container implementation, already be instantiated during deployment or once it has received an init_wscm request from a management client or a SOAP request from a web service client.

By default, when this attribute is omitted or contains an unknown value, the web service will configure itself immediately without waiting for configuration from a management client. Otherwise, if you want the web service instance to wait until it has received configuration, the start attribute needs to be set to notify:

<sunman:ManagedService id="user defined" start="notify"/>

Even when start is set to notify, the web service will still come up without any signal from a management client if it finds any persistent configuration in the Metro durable storage. This is to allow endpoints to recover from system failures and allows to operate in clusters where only one web service instance can receive a configuration signal.

19.7.2. Communication API

You can pass some configuration parameters into the default JMX communication implementation as well as specify your own communication implementations. The generic syntax is this:

<sunman:ManagedService id="user defined">
  <sunman:CommunicationServerImplementations>
    <sunman:CommunicationServerImplementation className="fully qualified class name">
      <ParameterName>value</ParameterName>
    </sunman:CommunicationServerImplementation>
    <sunman:CommunicationServerImplementation className="fully qualified class name">
      <ParameterName>value</ParameterName>
    </sunman:CommunicationServerImplementation>
  </sunman:CommunicationServerImplementations>
</sunman:ManagedService>

The CommuncationServerImplementation className attribute allows you to plug in one or more of your own implementations. The implementation must implement the com.sun.xml.ws.api.config.management.CommunicationServer interface. You can specify arbitrarily named parameters that your code will be able to read through com.sun.xml.ws.api.config.management.policy.ManagedServiceAssertion.

If you just want to set some configuration parameters for the default JMX implementation, do not specify the className attribute:

<sunman:ManagedService id="user defined">
  <sunman:CommunicationServerImplementations>
    <sunman:CommunicationServerImplementation>
      <sunman:JmxServiceUrl>value</sunman:JmxServiceUrl>
      <sunman:JmxConnectorServerEnvironment>
        <ParameterName>value</ParameterName>
      </sunman:JmxConnectorServerEnvironment>
      <sunman:JmxConnectorServerCreator>
        fully qualified class name
      </sunman:JmxConnectorServerCreator>
    </sunman:CommunicationServerImplementation>
  </sunman:CommunicationServerImplementations>
</sunman:ManagedService>

JMXServiceUrl allows you to specify what transport protocol and address the default JMX agent should be listening to. By default the following URL will be used: service:jmx:rmi:///jndi/rmi://localhost:8686/metro/ID, where ID is what was specified in the ManagedService id attribute.

JmxConnectorServiceEnvironment allows to pass parameters into the connector of the default JMX agent. This can be used to set security settings for example. There are some cases however where you need to pass objects other than Strings into the JMX connector service environment. Therefore it is possible to specify a custom class with JmxConnectorServerCreator that is expected to return an already initialized JMXConnectorServer. The JmxConnectorServerCreator must implement the interface com.sun.xml.ws.api.config.management.jmx.JmxConnectorServerCreator.

19.7.3. Configuration API

This allows you to plug in a custom com.sun.xml.ws.api.config.management.Configurator implementation:

<sunman:ManagedService id="user defined">
  <sunman:ConfiguratorImplementation className="fully qualified class name">
    <ParameterName>value</ParameterName>
  </sunman:ConfiguratorImplementation>>
</sunman:ManagedService>

The default Configurator implementation does not take any parameters, i.e. there is no need to provide this configuration statement if you don't want to plug in a custom implementation.

19.7.4. Persistence API

The persistence API consists of two interfaces, com.sun.xml.ws.api.config.management.ConfigSaver and com.sun.xml.ws.api.config.management.ConfigReader. ConfigSaver is meant to write the new service configuration to durable storage. ConfigReader is designed to run asynchronously (it can also be implemented to run synchronously however) and can e.g. poll the durable storage for configuration changes and kick off a service reconfiguration. You can specify your implementation classes like this:

<sunman:ManagedService id="user defined">
  <sunman:ConfigSaverImplementation className="fully qualified class name">
    <ParameterName>value</ParameterName>
  </sunman:ConfigSaverImplementation>>
  <sunman:ConfigReaderImplementation className="fully qualified class name">
    <ParameterName>value</ParameterName>
  </sunman:ConfigReaderImplementation>>
</sunman:ManagedService>

Again, if you want to configure the default implementations, leave away the className attribute:

<sunman:ManagedService id="user defined">
  <sunman:ConfigSaverImplementation className="fully qualified class name">
    <sunman:JdbcDataSourceName>value</<sunman:JdbcDataSourceName>
    <sunman:JdbcTableName>value</<sunman:JdbcTableName>
    <sunman:JdbcIdColumnName>value</<sunman:JdbcIdColumnName>
    <sunman:JdbcVersionColumnName>value</<sunman:JdbcVersionColumnName>
    <sunman:JdbcConfigColumnName>value</<sunman:JdbcConfigColumnName>
  </sunman:ConfigSaverImplementation>>
  <sunman:ConfigReaderImplementation className="fully qualified class name">
    <sunman:JdbcDataSourceName>value</<sunman:JdbcDataSourceName>
    <sunman:JdbcTableName>value</<sunman:JdbcTableName>
    <sunman:JdbcIdColumnName>value</<sunman:JdbcIdColumnName>
    <sunman:JdbcVersionColumnName>value</<sunman:JdbcVersionColumnName>
    <sunman:JdbcConfigColumnName>value</<sunman:JdbcConfigColumnName>
  </sunman:ConfigReaderImplementation>>
</sunman:ManagedService>

JdbcDataSourceName lets you customize the name of the JDBC DataSource. The name defaults to jdbc/metro/management.

JdbcTableName is the name of the database table that contains the configuration data. It defaults to METRO.

JdbcIdColumnName is the name of the column that holds the managed web service ID. It defaults to id and is expected to be of a type that can hold a JDBC String value. This column should be declared as a primary key. The default implementation does not impose any restrictions on the length of the web service ID.

JdbcVersionColumnName is the name of a column that provides a running counter and defaults to version. The counter is increased strictly monotonously when new configuration data is written to the table. This allows the implementation to efficiently establish if new data was written. The column type needs to map to a JDBC Long type.

JdbcConfigColumnName is the name of the column that holds the current configuration data and defaults to config. The data is read and written as a character BLOB. The column type must be suitable for use with a JDBC character stream.

If you change one of these settings for the ConfigSaverImplementation or the ConfigReaderImplementation, make sure that you are configuring the same setting for both implementations.


Terms of Use; Privacy Policy; Copyright ©2013-2014 (revision 20140418.2d69abc)
 
 
Close
loading
Please Confirm
Close