Detailed Development Software Installation Instructions

Follow these instructions:

In your .bashrc (or .zshrc, ...) add something like:

export JAVA_HOME=/usr/lib/jvm/java-1.5.0-sun

Under Mac OS X, if you have properly installed a JDK (XXX: check how), you will need to put in your your .bashrc (or .zshrc, ...) add something like:

export JAVA_HOME=/Library/Java/Home

JBoss is shipped with built-in Tomcat web server. This server is configured in 'deploy/jbossweb-tomcat55.sar/server.xml' By default only two connectors are enabled: HTTP connector (port 8080) and AJP connector (port 8009). Generally speaking you need only one of them. The former connector is needed if standalone HTTP server built in JBoss is used. You may want to configure it to listen the default HTTP port 80. The latter connector is needed only if you want to couple JBoss server with external web server like Apache, in this case it is reasonable, for security issues to change the binding address to 'localhost' (of course if Apache runs on the same host).

The JBoss default configuration deploys a special service that can be used to expose different JBoss services in the HTTP server. It is located in 'deploy/http-invoker.sar'. The configuration file 'deploy/http-invoker.sar/META-INF/jboss-service.xml' may be tweaked to tune the AS to specific needs. By default the service provides HTTP invoker MBean for EJB ('jboss:service=invoker,type=http') and two HTTP proxy MBeans that marshal the requests to the Naming service MBean ('jboss:service=invoker,type=http,target=Naming' and 'jboss:service=invoker,type=http,target=Naming,readonly=true'). If you need to provide HTTP interface to another MBeans, you also may specify the proxy services in 'deploy\http-invoker.sar\META-INF\jboss-service.xml'. For instance the SRP service for JBoss authentication may be exposed here.

The service also deploys web application 'deploy/http-invoker.sar/invoker.war', that configures the servlets that convert HTTP requests into invocation of MBeans/EJB methods. If you add HTTP proxies to MBeans, you may need to add servlets that handle the corresponding URI.

Important note. If HTTPS protocol is used the configuration should not use the default host name because the virtual host name used in the URL (say 'www.nuxeo.org') and exposed in SSL certificates usually differs from the computer name where JBoss is running. To accomplish this get rid of the following attributes: InvokerURLPrefix, InvokerURLSuffix, UseHostName, replacing them with a single InvokerURL attribute, like this:

<mbean code="org.jboss.invocation.http.server.HttpProxyFactory"
   name="jboss:service=invoker,type=https,target=Naming">
   <!-- Compose the invoker URL from the cluster node address -->
   <attribute name="InvokerURL">
      https://www.nuxeo.org/invoker/JMXInvokerServlet
   </attribute>
   <attribute name="ExportedInterface">
      org.jnp.interfaces.Naming
   </attribute>
   <attribute name="JndiName"></attribute>
   <attribute name="ClientInterceptors">
   <interceptors>
      <interceptor>org.jboss.proxy.ClientMethodInterceptor</interceptor>
      <interceptor>org.jboss.proxy.SecurityInterceptor</interceptor>
      <interceptor>org.jboss.naming.interceptors.ExceptionInterceptor</interceptor>
      <interceptor>org.jboss.invocation.InvokerInterceptor</interceptor>
   </interceptors>
   </attribute>
   <depends>jboss:service=invoker,type=https</depends>
</mbean>
<!-- The rest MBeans should also use InvokerURL attribute only,
   make sure you specify the right host name
-->

This is the core service of JBoss and should never be disabled. Nevertheless this service does not need own listening port (1099,1098), so just change the '1099' to '-1':

<mbean code="org.jboss.naming.NamingService"
   name="jboss:service=Naming"
   xmbean-dd="resource:xmdesc/NamingService-xmbean.xml">
   <!-- The call by value mode. true if all lookups are unmarshalled using
   the caller's TCL, false if in VM lookups return the value by reference.
   -->
   <attribute name="CallByValue">false</attribute>
   <!-- The listening port for the bootstrap JNP service. Set this to -1
     to run the NamingService without the JNP invoker listening port.
   -->
   <attribute name="Port">-1</attribute>
   <!-- The bootstrap JNP server bind address. This also sets the default
   RMI service bind address. Empty == all addresses, use localhost to hide this from 
   network
    -->
   <attribute name="BindAddress">localhost</attribute>
   <!-- The port of the RMI naming service, 0 == anonymous, you cannot use -1 here -->
   <attribute name="RmiPort">1098</attribute>
   <!-- The RMI service bind address. Empty == all addresses, use localhost to hide this from 
   network
    -->
   <attribute name="RmiBindAddress">localhost</attribute>
   <!-- The thread pool service used to control the bootstrap lookups -->
   <depends optional-attribute-name="LookupPool"
      proxy-type="attribute">jboss.system:service=ThreadPool</depends>
</mbean>

You may deinstall the JRMP and Pooled invokers completely. Just comment out the MBeans that provide the corresponding services in 'conf/jboss-service.xml'.

Important note. The JBoss specifies the invokers for EJB in 'conf/standardjboss.xml' file. The default is 'jboss:service=invoker,type=jrmp' invoker. To change it to HTTP invoker you need to add invoker bindings for all EJB types deployed in your applications. Generally it means you need to copy all "*-rmi-invoker" bindings into "*-http-invoker" bindings, replacing "<invoker-mbean>jboss:service=invoker,type=jrmp</invoker-mbean>" with "<invoker-mbean>jboss:service=invoker,type=http</invoker-mbean>" for the new bindings. Also you will need to make the HTTP invoker default for all EJB container configurations replacing "<invoker-proxy-binding-name>*-rmi-invoker</invoker-proxy-binding-name>" with "<invoker-proxy-binding-name>*-http-invoker</invoker-proxy-binding-name>" correspondingly.

The easiest (but probably not the right) way for JBoss 4.0.x is to replace the string 'jboss:service=invoker,type=jrmp' with 'jboss:service=invoker,type=http' in this file by any text editor. It may be not correct if you want to mix both invokers for your EJBs.

The EJB3 invoker which is specified in 'deploy/ejb3.deployer/META-INF/jboss-service.xml' uses JBoss remoting mechanism. By default it is bound to socket with a connector listening TCP/IP port 3873. This should be changed to the servlet locator:

<mbean code="org.jboss.remoting.transport.Connector"
       name="jboss.remoting:type=Connector,name=DefaultEjb3Connector,handler=ejb3">
   <depends>jboss.aop:service=AspectDeployer</depends>
   <attribute name="InvokerLocator">
      servlet://${jboss.bind.address}/invoker/Ejb3InvokerServlet
   </attribute>
   <attribute name="Configuration">
      <handlers>
         <handler subsystem="AOP">org.jboss.aspects.remoting.AOPRemotingInvocationHandler</handler>
      </handlers>
   </attribute>
</mbean>

The corresponding servlet should be added to invoker web application descriptor ('http-invoker.sar/invoker.war/WEB-INF/web.xml'):

<servlet>
   <servlet-name>Ejb3InvokerServlet</servlet-name>
   <description>
      The ServerInvokerServlet receives requests via HTTP protocol
      from within a web container and passes it onto the
      ServletServerInvoker for processing.
   </description>
   <servlet-class>
      org.jboss.remoting.transport.servlet.web.ServerInvokerServlet
   </servlet-class>
   <init-param>
      <param-name>locatorUrl</param-name>
      <param-value>
         servlet://${jboss.bind.address}/invoker/Ejb3InvokerServlet
      </param-value>
      <description>
         The servlet server invoker locator url
      </description>
   </init-param>
   <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
   <servlet-name>Ejb3InvokerServlet</servlet-name>
   <url-pattern>/Ejb3InvokerServlet/*</url-pattern>
</servlet-mapping>

The Client User Transaction service depends on two JRMP Proxy Factories described in the nested MBeans. Every JRMP proxy factory should be replaced with HTTP proxy factory:

<mbean
   code="org.jboss.tm.usertx.server.ClientUserTransactionService"
   name="jboss:service=ClientUserTransaction"
   xmbean-dd="resource:xmdesc/ClientUserTransaction-xmbean.xml">
  <depends>
    <mbean code="org.jboss.invocation.http.server.HttpProxyFactory"
         name="jboss:service=proxyFactory,target=ClientUserTransactionFactory">
      <attribute name="InvokerName">jboss:service=invoker,type=http</attribute>
      <attribute name="JndiName">UserTransactionSessionFactory</attribute>
      <attribute name="ExportedInterface">
        org.jboss.tm.usertx.interfaces.UserTransactionSessionFactory
      </attribute>
      <attribute name="ClientInterceptors">
        <interceptors>
          <interceptor>org.jboss.proxy.ClientMethodInterceptor</interceptor>
          <interceptor>org.jboss.invocation.InvokerInterceptor</interceptor>
        </interceptors>
      </attribute>
      <depends>jboss:service=invoker,type=http</depends>
    </mbean>
  </depends>
  <depends optional-attribute-name="TxProxyName">
    <mbean code="org.jboss.invocation.http.server.HttpProxyFactory"
         name="jboss:service=proxyFactory,target=ClientUserTransaction">
      <attribute name="InvokerName">jboss:service=invoker,type=http</attribute>
      <attribute name="JndiName"></attribute>
      <attribute name="ExportedInterface">
        org.jboss.tm.usertx.interfaces.UserTransactionSession
      </attribute>
      <attribute name="ClientInterceptors">
        <interceptors>
          <interceptor>org.jboss.proxy.ClientMethodInterceptor</interceptor>
          <interceptor>org.jboss.invocation.InvokerInterceptor</interceptor>
        </interceptors>
      </attribute>
      <depends>jboss:service=invoker,type=http</depends>
    </mbean>
  </depends>
</mbean>

Note that JRMP Proxy factory attributes differ from attributes of HTTP proxy factory.

The JMX adaptor is adapted for HTTP as following ('deploy/jmx-invoker-service.xml'):

<mbean code="org.jboss.invocation.http.server.HttpProxyFactory"
       name="jboss.jmx:type=adaptor,name=Invoker,protocol=http,service=proxyFactory">
  <attribute name="InvokerURL">https://www.nuxeo.org/invoker/JMXInvokerServlet</attribute>
  <depends optional-attribute-name="InvokerName">jboss.jmx:type=adaptor,name=Invoker</depends>
  <attribute name="ExportedInterface">org.jboss.jmx.adaptor.rmi.RMIAdaptor</attribute>
  <attribute name="JndiName">jmx/invoker/HttpAdaptor</attribute>
</mbean>

and ('deploy/console-mgr.sar/META-INF/jboss-service.xml'):

<mbean code="org.jboss.console.manager.PluginManager"
       name="jboss.admin:service=PluginManager">
  <depends>jboss.jmx:type=adaptor,name=Invoker,protocol=http,service=proxyFactory</depends>
  <!-- the rest stays intact -->
</mbean>

You need to set the invoker explicitly for all deployed data sources. The element <jmx-invoker-name> should be added to all <local-tx-datasource> and <xa-datasource> elements. Otherwise the server will complain about missing JRMP invoker which is used by default:

<datasources>
        ...
   <local-tx-datasource>
      <!-- specify explicitly the invoker to use -->
      <jmx-invoker-name>jboss:service=invoker,type=https</jmx-invoker-name>
      <!-- the rest stays intact -->
               ...
   </local-tx-datasource>
        ...
</datasources>