Service Deployment

Services are deployed in one of three ways:

1. -service.xml files

2. sar files with a META-INF/jboss-service of the -service.xml format

3. programmatically

Elements

There are many elements to this file - see the dtd mentioned at the end for full information.

The key elements are:

• code

  - the class that implements the service

• name

  - the JMX ObjectName that uniquely identifies the service

• attribute

  - configures the attributes of the service, the attribute can be of any type that has a PropertyEditor

• depends

  - creates a dependency to another service

Example

<server>
  <mbean code="com.acme.ExampleService"
         name="acme.com:service=example">
     <!-- A plain attribute -->
     <attribute name="Message">hello</attribute>
     <!-- An integer -->
     <attribute name="Repeated">1</attribute>
     <!-- A boolean -->
     <attribute name="Beep">false</attribute>
     <!-- An attribute with a property editor, it is actually an InetAddress -->
     <attribute name="BindAddress">192.168.0.1</attribute>
     <!-- An attribute of type org.w3c.dom.Element containing embedded xml -->
     <attribute name="Element">
         <some>
            <embedded-xml-passed-to-the-service></embedded-xml-passed-to-the-service>
         </some>
     </attribute>
     <!-- An attribute defined intialised with the system property user.name -->
     <attribute name="UserName>${user.name}</attribute>
     <!-- A dependency on another service -->
     <depends>acme.com:service=another</depends>
     <!-- A dependency that also passes the ObjectName to the configured attribute -->
     <depends optional-attribute-name="Another">acme.com:service=another</depends>
     <!-- A dependency that passes an MBeanProxy to the attribute using the attribute's class as the interface -->
     <depends optional-attribute-name="Another" proxy-type="attribute">acme.com:service=another</depends>
     <!-- A dependency that passes an MBeanProxy to the attribute using the specified class as the interface -->
     <depends optional-attribute-name="Another" proxy-type="com.acme.SomeInterface">acme.com:service=another</depends>
   </mbean>
</server>

The supported attribute styles

There are three types of attribute usage styles that differ in how the attribute xml representation is transformed into a java object representation. The attribute style is determined by the serialDataType attribute of the attribute element. The currently supported values for the serialDataType attribute are text, javaBean, and jbxb.

Text style attributes

The serialDataType="text" is the default, and legacy style that is used when no serialDataType attribute value is specified. For text style attribute values, the content of the attribute element is treated as the string representation of the attribute value. It will be mapped to the attribute using the java.beans.PropertyEditor registered for the attribute type.

  <mbean code="com.acme.ExampleService"
         name="acme.com:service=example">
     <!-- An attribute with a property editor, it is actually an InetAddress -->
     <attribute serialDataType="text" name="BindAddress">192.168.0.1</attribute>
...

JavaBean style attributes (4.0.2+)

The serialDataType="javaBean" style treats the attribute element content is a collection of property elements that map to properties of the MBean attribute class. The exact class of the JavaBean to use can be specified via the attributeClass attribute. The context of the property elements are treated the same as text style attributes. The property text is converted to an object using the java.beans.PropertyEditor associated with the JavaBean property type. The following RMIServerSocketFactoryBean attributes uses the javaBean style to configure a org.jboss.security.ssl.RMISSLServerSocketFactory JavaBean:

   <mbean code="org.jboss.invocation.jrmp.server.JRMPInvoker"
      name="jboss.security:service=invoker,type=jrmp,socketType=SSLSocketFactory,wantsClientAuth=true">
      <attribute name="RMIObjectPort">0</attribute>
      <attribute name="RMIClientSocketFactory">org.jboss.security.ssl.RMISSLClientSocketFactory
      </attribute>
      <attribute name="RMIServerSocketFactoryBean"
         attributeClass="org.jboss.security.ssl.RMISSLServerSocketFactory"
         serialDataType="javaBean">
         <property name="bindAddress">${jboss.bind.address}</property>
         <property name="securityDomain">java:/jaas/rmi-ssl</property>
         <property name="wantsClientAuth">true</property>
         <property name="CiperSuites">true</property>
         <property name="CiperSuites">true</property>
      </attribute>
   </mbean>

jbxb style attributes (4.0.2+)

The serialDataType="jbxb" style treats the attribute element content as an xml element from a namespace with an associated xml schema that can be unmarshalled using the JBossXB framework. The following BindingsConfig attribute example usage illustrates a complex object that is made up of an xml fragment with portions from two schemas,

jndi-binding-service_1_0.xsd and java-properties_1_0.xsd:

<server>
   <mbean code="org.jboss.naming.JNDIBindingServiceMgr"
         name="jboss.tests:service=JNDIBindingServiceMgr">
      <attribute name="BindingsConfig" serialDataType="jbxb">
         <jndi:bindings
            xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
            xmlns:jndi="urn:jboss:jndi-binding-service:1.0"
            xs:schemaLocation="urn:jboss:jndi-binding-service:1.0 resource:jndi-binding-service_1_0.xsd"
            >
            <jndi:binding name="urls/jboss-home">
               <jndi:value type="java.net.URL">http://www.jboss.org</jndi:value>
            </jndi:binding>

            <jndi:binding name="hosts/localhost">
               <jndi:value editor="org.jboss.util.propertyeditor.InetAddressEditor">
                  127.0.0.1
               </jndi:value>
            </jndi:binding>

            <jndi:binding name="maps/testProps">
               <java:properties xmlns:java="urn:jboss:java-properties"
                  xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
                  xs:schemaLocation="urn:jboss:java-properties resource:java-properties_1_0.xsd">
                  <java:property>
                     <java:key>key1</java:key>
                     <java:value>value1</java:value>
                  </java:property>
                  <java:property>
                     <java:key>key2</java:key>
                     <java:value>value2</java:value>
                  </java:property>
               </java:properties>               
            </jndi:binding>
         </jndi:bindings>
      </attribute>
   </mbean>

</server>

System Property References

Any attribute value can use a system property reference of the form ${x,y:z} to reference a system property, an alternate system property y, and a default static value z. If the system property x is defined it will used, otherwise if the system property y is defined it will used, otherwise the default value will be used. the y and z elements are optional. Examples:

use user.home system property if define, else use java.io.tmpdir if defined, else use /tmp
${user.home,java.io.tmpdir,/tmp}

Related

The 3.2 -service.xml DTD or docs/dtd/jboss-service_3_2.dtd in the JBoss distribution.

The 4.0 jboss-service.xml DTD or docs/dtd/jboss-service_4_0.dtd in the JBoss distribution.