The current documentation on the UnifiedInvoker and UnifiedInvokerHA can be found at http://docs.jboss.org/jbossas/unified_invoker/UnifiedInvoker_guide.html, which applies to JBossAS 4.0.4 and JBoss 5 (which is at CVS HEAD).
The following is out of date and will be removed in the near future.
Click to see directions for SSL with EJB2.1 or SSL with EJB3
Since the Unified Invoker depends on JBoss Remoting, configuration is really divided into two parts, the remoting configuration and the unified invoker configuration. It is important to understand how the two interact to understand the configuration.
First is the Unified Invoker configuration. There is nothing really special about declaring this service other than need to make sure have the proper dependencies, which are on the remoting connector and transaction manager. An example of this configuration would be:
<mbean code="org.jboss.invocation.unified.server.UnifiedInvoker" name="jboss:service=invoker,type=unified"> <depends>jboss:service=TransactionManager</depends> <depends>jboss.remoting:service=Connector,transport=socket</depends> </mbean>
Next is the remoting configuration. This is nothing special, just configure with the the transport desired as usual. Only difference that the Unified Invoker requires a special marshaller/unmarshaller to convert invocation across the wire (this so can convert transaction and such, which are not serializable). This means will need to add the data type as a parameter to the locator url.
Will also have to specify the Unfified Invoker as the handler for remoting. An simple example of this configuration is:
<mbean code="org.jboss.remoting.transport.Connector" xmbean-dd="org/jboss/remoting/transport/Connector.xml" name="jboss.remoting:service=Connector,transport=socket" display-name="Socket transport Connector"> <attribute name="InvokerLocator"><![CDATA[socket://localhost:8081/?datatype=invocation\]\]\></attribute> <attribute name="Configuration"> <handlers> <handler subsystem="invoker">jboss:service=invoker,type=unified</handler> </handlers> </attribute> <depends>jboss.remoting:service=NetworkRegistry</depends> </mbean>
The only other, VERY IMPORTANT, part of this configuration is that the unified invoker configuration MUST be declared before the Connector in the jboss-service.xml configuration. This is important because when the Connector starts up, it will set the server invoker on the handler. If the handler, in this case the unified invoker, is not present an Exception will be thrown.
The following is an example of the full configuration needed for the Unified Invoker to work correctly:
<mbean code="org.jboss.invocation.unified.server.UnifiedInvoker" name="jboss:service=invoker,type=unified"> <depends>jboss:service=TransactionManager</depends> <depends>jboss.remoting:service=Connector,transport=socket</depends> </mbean> <mbean code="org.jboss.remoting.network.NetworkRegistry" name="jboss.remoting:service=NetworkRegistry"></mbean> <mbean code="org.jboss.remoting.transport.Connector" xmbean-dd="org/jboss/remoting/transport/Connector.xml" name="jboss.remoting:service=Connector,transport=socket" display-name="Socket transport Connector"> <attribute name="InvokerLocator"><![CDATA[socket://localhost:8081/?datatype=invocation\]\]\></attribute> <attribute name="Configuration"> <handlers> <handler subsystem="invoker">jboss:service=invoker,type=unified</handler> </handlers> </attribute> <depends>jboss.remoting:service=NetworkRegistry</depends> </mbean>
The only extra part added was the NetworkRegistry, which is needed by the Connector. For an example of the full blown configuration for remoting and unified invoker, see bottom of page.
Now, all that is needed is to update the standardjboss.xml to declare that the Unified Invoker should be used instead of the default detached invoker (which is the JRMPInvoker). In JBoss 5.0, the Unified Invoker will probably be the default, so may not need to make this change. For more information on changing the detached invoker used by the container, please see Chapter 5 of the Admin/Developer's Guide
As of 5/3/05 there was an additional property added to the UnifiedInvoker (StrictRMIException) due to JBREM-61 (see http://jira.jboss.com/jira/browse/JBREM-61 for more information). This change was made to jboss-head (CVS HEAD, so is a JBossAS 5 change).
The UnifiedInvoker/UnifiedInvokerProxy was changed so that there is now a StrictRMIException property which is false by default. When false, will just take any RemoteException and throw it. If true, will catch any RemoteException and re-throw it in a wrapped ServerException.
I also changed the server/src/etc/conf/default/jboss-service.xml to be:
<!-- Unified invoker (based on remoting) --> <mbean code="org.jboss.invocation.unified.server.UnifiedInvoker" name="jboss:service=invoker,type=unified"> <!-- To turn on strict RMI exception propagation uncomment block below --> <!-- This will cause the UnifiedInvokerProxy to wrap RemoteExceptions --> <!-- within a ServerException, otherwise will throw root exception --> <!-- (not RemoteException) --> <!-- <attribute name="StrictRMIException">true</attribute> --> <depends>jboss:service=TransactionManager</depends> <depends>jboss.remoting:service=Connector,transport=socket</depends> </mbean>
UnifiedInvoker with rmi transport
To use the rmi transport, only need to change the connector configuration to use the rmi transport. An example snippet for rmi transport within the connector for use with the UnifiedInvoker is
<attribute name="Configuration">
<config>
<invoker transport="rmi">
<attribute name="marshaller" isParam="true">org.jboss.invocation.unified.marshall.InvocationMarshaller</attribute>
<attribute name="unmarshaller" isParam="true">org.jboss.invocation.unified.marshall.InvocationUnMarshaller</attribute>
<attribute name="serverBindAddress">${jboss.bind.address}</attribute>
<attribute name="serverBindPort">6668</attribute>
</invoker>
<handlers>
<!-- can also specify handler by fully qualified classname -->
<handler subsystem="invoker">jboss:service=invoker,type=unified</handler>
</handlers>
</config>
</attribute>
<depends>jboss.remoting:service=NetworkRegistry</depends>
</mbean>
UnifiedInvoker with http(s) transport
To use http or https transports, will require changing the connector configuration to use the http/https transport and the HTTPInvocationMarshaller/HTTPInvocationUnMarshaller. The following is an example of the full configuration snippet for https
<mbean code="org.jboss.remoting.transport.Connector"
xmbean-dd="org/jboss/remoting/transport/Connector.xml"
name="jboss.remoting:service=Connector,transport=https"
display-name="HTTPS transport Connector">
<attribute name="Configuration">
<config>
<invoker transport="https">
<attribute name="marshaller" isParam="true">org.jboss.invocation.unified.marshall.HTTPInvocationMarshaller</attribute>
<attribute name="unmarshaller" isParam="true">org.jboss.invocation.unified.marshall.HTTPInvocationUnMarshaller</attribute>
<attribute name="serverSocketFactory">jboss.remoting:service=ServerSocketFactory,type=SSL</attribute>
<attribute name="serverBindAddress">${jboss.bind.address}</attribute>
<attribute name="serverBindPort">6669</attribute>
</invoker>
<handlers>
<!-- can also specify handler by fully qualified classname -->
<handler subsystem="invoker">jboss:service=invoker,type=unified</handler>
</handlers>
</config>
</attribute>
<depends>jboss.remoting:service=ServerSocketFactory,type=SSL</depends>
<depends>jboss.remoting:service=NetworkRegistry</depends>
</mbean>
<mbean code="org.jboss.remoting.security.SSLSocketBuilder"
name="jboss.remoting:service=SocketBuilder,type=SSL"
display-name="SSL Server Socket Factory Builder">
<!-- IMPORTANT - If making ANY customizations, this MUST be set to false. -->
<!-- Otherwise, will used default settings and the following attributes will be ignored. -->
<attribute name="UseSSLServerSocketFactory">false</attribute>
<!-- This is the url string to the key store to use -->
<attribute name="KeyStoreURL">${jboss.server.data.dir}/.keystore</attribute>
<!-- The password for the key store -->
<attribute name="KeyStorePassword">opensource</attribute>
<!-- The password for the keys (will use KeystorePassword if this is not set explicitly. -->
<attribute name="KeyPassword">opensource</attribute>
<!-- The protocol for the SSLContext. Default is TLS. -->
<attribute name="SecureSocketProtocol">TLS</attribute>
<!-- The algorithm for the key manager factory. Default is SunX509. -->
<attribute name="KeyManagementAlgorithm">SunX509</attribute>
<!-- The type to be used for the key store. -->
<!-- Defaults to JKS. Some acceptable values are JKS (Java Keystore - Sun's keystore format), -->
<!-- JCEKS (Java Cryptography Extension keystore - More secure version of JKS), and -->
<!-- PKCS12 (Public-Key Cryptography Standards #12 keystore - RSA's Personal Information Exchange Syntax Standard). -->
<!-- These are not case sensitive. -->
<attribute name="KeyStoreType">JKS</attribute>
</mbean>
<!-- The server socket factory mbean to be used as attribute to socket invoker --> <!-- See serverSocketFactory attribute above for where it is used --> <!-- This service provides the exact same API as the ServerSocketFactory, so --> <!-- can be set as an attribute of that type on any MBean requiring an ServerSocketFactory. --> <mbean code="org.jboss.remoting.security.SSLServerSocketFactoryService" name="jboss.remoting:service=ServerSocketFactory,type=SSL" display-name="SSL Server Socket Factory"> <depends optional-attribute-name="SSLSocketBuilder" proxy-type="attribute">jboss.remoting:service=SocketBuilder,type=SSL</depends> </mbean>
Notice that the marshaller and unmarshaller attribute values as well the addition of the dependancy of the server socket factory service. For more information on server socket factory service configuration and SSL see http://wiki.jboss.org/wiki/Wiki.jsp?page=Remoting_SSL_Support.
Full configuration example
This configuration shows everything in detail for unified invoker and remoting. Can simply copy and past into jboss-service.xml.
<!-- Unified invoker (based on remoting) -->
<mbean code="org.jboss.invocation.unified.server.UnifiedInvoker"
name="jboss:service=invoker,type=unified">
<!-- To turn on strict RMI exception propagation uncomment block below -->
<!-- This will cause the UnifiedInvokerProxy to wrap RemoteExceptions -->
<!-- within a ServerException, otherwise will throw root exception -->
<!-- (not RemoteException) -->
<!-- <attribute name="StrictRMIException">true</attribute> -->
<depends>jboss:service=TransactionManager</depends>
<depends>jboss.remoting:service=Connector,transport=socket</depends>
</mbean>
<!-- ==================================================================== -->
<!-- Remoting services -->
<!-- ==================================================================== -->
<!-- For detailed description of all these configuration attributes, please see the -->
<!-- JBoss Remoting User's Guide or wiki (http://www.jboss.org/wiki/Wiki.jsp?page=Remoting_configuration) -->
<!-- The NetworkRegistry contains all the local and remote -->
<!-- servers that it recognizes. The remote ones registered -->
<!-- are dependant on the detectors running and which domains -->
<!-- they are configured to identify. -->
<mbean code="org.jboss.remoting.network.NetworkRegistry"
name="jboss.remoting:service=NetworkRegistry"></mbean>
<!-- The Connector is the core component of the remoting server service. -->
<!-- It binds the remoting invoker (transport protocol, callback configuration, -->
<!-- data marshalling, etc.) with the invocation handlers. -->
<mbean code="org.jboss.remoting.transport.Connector"
xmbean-dd="org/jboss/remoting/transport/Connector.xml"
name="jboss.remoting:service=Connector,transport=socket"
display-name="Socket transport Connector">
<!-- Can either just specify the InvokerLocator attribute and not the invoker element in the -->
<!-- Configuration attribute, or do the full invoker configuration in the in invoker element -->
<!-- of the Configuration attribute. -->
<!-- Remember that if you do use more than one param on the uri, will have to include as a CDATA, -->
<!-- otherwise, parser will complain. -->
<!-- <attribute name="InvokerLocator"><![CDATA[socket://${jboss.bind.address}:4446/?datatype=invocation\]\]\></attribute> -->
<attribute name="Configuration">
<!-- Using the following <invoker> element instead of the InvokerLocator above because specific attributes needed. -->
<!-- If wanted to use any of the parameters below, can just add them as parameters to the url above if wanted use the InvokerLocator attribute. -->
<config>
<!-- Other than transport type and handler, none of these configurations are required (will just use defaults). -->
<invoker transport="socket">
<attribute name="dataType" isParam="true">invocation</attribute>
<attribute name="marshaller" isParam="true">org.jboss.invocation.unified.marshall.InvocationMarshaller</attribute>
<attribute name="unmarshaller" isParam="true">org.jboss.invocation.unified.marshall.InvocationUnMarshaller</attribute>
<!-- This will be port on which the marshall loader port runs on. -->
<!-- <attribute name="loaderport" isParam="true">4447</attribute> -->
<!-- The following are specific to socket invoker -->
<!-- <attribute name="numAcceptThreads">1</attribute>-->
<!-- <attribute name="maxPoolSize">303</attribute>-->
<!-- <attribute name="clientMaxPoolSize" isParam="true">304</attribute>-->
<!-- <attribute name="socketTimeout">60000</attribute>-->
<attribute name="serverBindAddress">${jboss.bind.address}</attribute>
<attribute name="serverBindPort">4446</attribute>
<!-- <attribute name="clientConnectAddress">216.23.33.2</attribute> -->
<!-- <attribute name="clientConnectPort">7777</attribute> -->
<!-- <attribute name="enableTcpNoDelay" isParam="true">false</attribute>-->
<!-- <attribute name="backlog">200</attribute>-->
<!-- The following is for callback configuration and is independant of invoker type -->
<!-- <attribute name="callbackMemCeiling">30</attribute>-->
<!-- indicates callback store by fully qualified class name -->
<!-- <attribute name="callbackStore">org.jboss.remoting.CallbackStore</attribute>-->
<!-- indicates callback store by object name -->
<!-- <attribute name="callbackStore">jboss.remoting:service=CallbackStore,type=Serializable</attribute> -->
<!-- config params for callback store. if were declaring callback store via object name, -->
<!-- could have specified these config params there. -->
<!-- StoreFilePath indicates to which directory to write the callback objects. -->
<!-- The default value is the property value of 'jboss.server.data.dir' and if this is not set, -->
<!-- then will be 'data'. Will then append 'remoting' and the callback client's session id. -->
<!-- An example would be 'data\remoting\5c4o05l-9jijyx-e5b6xyph-1-e5b6xyph-2'. -->
<!-- <attribute name="StoreFilePath">callback</attribute>-->
<!-- StoreFileSuffix indicates the file suffix to use for the callback objects written to disk. -->
<!-- The default value for file suffix is 'ser'. -->
<!-- <attribute name="StoreFileSuffix">cst</attribute>-->
</invoker>
<!-- At least one handler is required by the connector. If have more than one, must decalre -->
<!-- different subsystem values. Otherwise, all invocations will be routed to the only one -->
<!-- that is declared. -->
<handlers>
<!-- can also specify handler by fully qualified classname -->
<handler subsystem="invoker">jboss:service=invoker,type=unified</handler>
</handlers>
</config>
</attribute>
<depends>jboss.remoting:service=NetworkRegistry</depends>
</mbean>
Comments