Chapter 3. Declarative configuration

When used in a standalone manner, Remoting clients and servers can be configured either by adding parameters to the InvokerLocator or by directly passing configuration maps to their constructors. In the context of the Application Server, however, Remoting objects are configured in xml files. There are two variations. In versions 4 and earlier of the Application Server, the various components are held together by an MBeanServer, and, in the course of initializing the Application Server, deployers create MBeans from xml description files. In version 5, the primacy of the MBeanServer has been replaced by the JBoss Microcontainer, which creates POJOs from xml description files. Both MBean and POJO descriptors are available in version 5.

3.1. MBean descriptors

An MBean descriptor of a Remoting Connector looks like the following abbreviated version derived from a JBoss Messaging example:

   <mbean code="org.jboss.remoting.transport.Connector"
          name="jboss.messaging:service=Connector,transport=bisocket"
          display-name="Bisocket Transport Connector">
      <attribute name="Configuration">
         <config>
            <invoker transport="bisocket">
               ...         
               <attribute name="serverBindAddress">localhost</attribute>
               <attribute name="serverBindPort">4457</attribute>
               <attribute name="marshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
               <attribute name="unmarshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
               <attribute name="timeout" isParam="true">300000</attribute>
               <attribute name="callbackTimeout">10000</attribute> 
               ...
            </invoker>
            <handlers>
               <handler subsystem="JMS">org.jboss.jms.server.remoting.JMSServerInvocationHandler</handler>
            </handlers>
         </config>
      </attribute>
   </mbean>
   

In this case, the Connector reads the <config> attribute and creates the InvokerLocator

bisocket://localhost:4457?marshaller=org.jboss.jms.wireformat.JMSWireFormat&unmarshaller=org.jboss.jms.wireformat.JMSWireFormat&timeout=300000
   

which is passed into the BisocketServerInvoker that it creates (see The bisocket transport chapter).

Notes.

  1. The <transport> element specifies that this Connector will create a BisocketServerInvoker.
  2. The "marshaller", "unmarshaller", and "timeout" parameters, which are all specified with the "isParam" attribute set to "true", appear in the InvokerLocator. They will be available on both the server side and the client side.
  3. The "callbackTimeout" parameter, which is specified without the "isParam" attribute, does not appear in the InvokerLocator. It will be available on the server side but will not be available on the client side.
  4. The <handler> element tells the Connector to create an instance of org.jboss.jms.server.remoting.JMSServerInvocationHandler to handle all invocations associated with the "JMS" subsystem.

3.2. POJO descriptors

When an MBean descriptor like the one in the previous section is given, the Connector explicitly parses the <config> element. In Application Server 5 and EAP 5, the microcontainer automatically parses POJO descriptors written in its descriptor language, creates the described POJOs, and can inject them into other POJOs. Remoting uses a POJO descriptor of a org.jboss.remoting.ServerConfiguration object to inject configuration information into a Connector. For example, the following POJO descriptors are abbreviated and modified versions of those used by the EJB2 subsystem:

   
   <bean name="UnifiedInvokerConnector" class="org.jboss.remoting.transport.Connector">
      <property name="serverConfiguration"><inject bean="UnifiedInvokerConfiguration"/></property>
   </bean>
   
   <bean name="UnifiedInvokerConfiguration" class="org.jboss.remoting.ServerConfiguration">
      <constructor>
         <parameter>socket</parameter>
      </constructor>
   
      <!-- Parameters visible to both client and server -->
      <property name="invokerLocatorParameters">
         <map keyClass="java.lang.String" valueClass="java.lang.String">
            <entry>
               <key>serverBindAddress</key>
               <value>localhost</value>
            </entry>
            <entry>
               <key>serverBindPort</key>
               <value>4446</value>
            </entry>
            <entry><key>enableTcpNoDelay</key> <value>true</value></entry>
         </map>
      </property>
     
      <!-- Parameters visible only to server -->
      <property name="serverParameters">
         <map keyClass="java.lang.String" valueClass="java.lang.String">
            <entry><key>maxPoolSize</key><value>500</value></entry>
         </map>
      </property>
                                
      <property name="invocationHandlers">
         <map keyClass="java.lang.String" valueClass="java.lang.String">
            <entry><key>JSR88</key> <value>org.jboss.deployment.remoting.DeployHandler</value></entry>
         </map>
      </property>
   </bean>
   

Here, the ServerConfiguration is created and injected into the Connector object, which creates the InvokerLocator

socket://localhost:4446?enableTcpNoDelay=true

Notes.

  1. The <constructor> element specifies that this Connector will create a SocketServerInvoker.
  2. The entries in the "invokerLocatorParameters" property appear in the InvokerLocator and are available on both the client and server sides.
  3. The entries in the "serverParameters" property do not appear in the InvokerLocator and are available only on the server side.
  4. The "invocationHandlers" property tells the Connector to create an instance of org.jboss.deployment.remoting.DeployHandler to handle all invocations associated with the "JSR88" subsystem.

The actual ServerInvocationHandler used by EJB2, by the way, is an instance of a different class and is injected into the SocketServerInvoker programmatically. It is described by the following POJO descriptor:

   <bean name="UnifiedInvoker" class="org.jboss.invocation.unified.server.UnifiedInvoker">
      <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss:service=invoker,type=unified",exposedInterface=org.jboss.invocation.unified.server.UnifiedInvokerMBean.class,registerDirectly=true)</annotation>
      <property name="connector"><inject bean="UnifiedInvokerConnector"/></property>
      <depends>TransactionManager</depends>
   </bean>
   

An org.jboss.invocation.unified.server.UnifiedInvoker is a ServerInvocationHandler, and it uses the "UnifiedInvokerConnector" to inject itself into the SocketServerInvoker created by the "UnifiedInvokerConnector". The <annotation> property, by the way, is used to assign an MBean name to a POJO.

There is an alternative way to configure a Connector with a ServerConfiguration. In the following modified version of two POJOs used by the EJB3 subsystem, the InvokerLocator is given explicitly to the Connector and the injected ServerConfiguration is used only to specify a ServerInvocationHandler:

   <bean name="org.jboss.ejb3.RemotingConnector"
     class="org.jboss.remoting.transport.Connector">

      <property name="invokerLocator">
         <value>socket://localhost:3873?timeout=300000</value>
      </property>
      <property name="serverConfiguration">
         <inject bean="ServerConfiguration" />
      </property>
   </bean>

   <!-- Remoting Server Configuration -->
   <bean name="ServerConfiguration"
     class="org.jboss.remoting.ServerConfiguration">
      <property name="invocationHandlers">
         <map keyClass="java.lang.String" valueClass="java.lang.String">
            <entry>
               <key>AOP</key>
               <value>
                  org.jboss.aspects.remoting.AOPRemotingInvocationHandler
               </value>
            </entry>
         </map>
      </property>
   </bean>