User: mulder
Date: 00/10/02 10:43:28
Modified: manual clients.html deploying.html index.html manual.css
warning.html
Log:
Add the clients section.
Update the style sheet to force a fixed-width font for <code> blocks, since
Netscape on Linux doesn't seem to do it if you've overridden the font for
the surrounding text.
Clarify the sections of jboss.xml that are based on declarations in
ejb-jar.xml.
Revision Changes Path
1.2 +275 -0 jbossweb/manual/clients.html
Index: clients.html
===================================================================
RCS file: /products/cvs/ejboss/jbossweb/manual/clients.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- clients.html 2000/09/14 18:28:35 1.1
+++ clients.html 2000/10/02 17:43:26 1.2
@@ -5,5 +5,280 @@
</head>
<body>
<h1 ALIGN="CENTER">jBoss 2.0: jBoss Clients</h1>
+ <p>Virtually any type of Java client can be a jBoss client. There
+ are several requirements for an EJB client:</p>
+ <ul>
+ <li>The client must have the jBoss client JARs and certain J2EE
+ specification JARs available (unless you use the advanced
+ dynamic classloading techniques)</li>
+ <li>You must provide JNDI settings to contact the server</li>
+ <li>The client's security manager must permit things like network
+ access, reading JNDI configuration files or system properties,
+ etc.</li>
+ </ul>
+ <p>These requirements are the same across all types of clients,
+ though each may differ in implementation (how to distribute jBoss
+ client JARs, for example).</p>
+
+ <h2><a NAME="jdk">Supported Java Versions</a></h2>
+ <p>jBoss supports Java 2 (currently, JDK 1.2.2-1.3.0). There has
+ been speculation that it may work under Java 1.x, but this is
+ not currently a supported platform. If your server is configured
+ for 1.3, then all clients must use 1.3. If your server is
+ configured for 1.2, then your clients may use 1.2 or 1.3. Note
+ that the server can be configured for 1.2 even if running under
+ 1.3 - it's just a matter of the network protocol used. However,
+ the 1.3 configuration is more efficient since some of the features
+ we depend on in the JDK have been implemented in native code.</p>
+ <p>The server is configured by default for JDK 1.3. To change it
+ to support 1.2, you need to change the
+ <code>container-invoker</code> setting for the server itself or
+ the specific EJB JARs you want to change over. This setting is
+ located in the <code>jboss.xml</code> configuration file for an
+ EJB JAR, and the server default is stored in a file called
+ <code>defaultjboss.xml</code>. Currently, this file is packaged
+ in the <code>ejxjboss.jar</code> file, so to make the global
+ change, you would have to unpack the jar, change the file, and
+ then re-jar it. In a future release, this will be moved to the
+ <b>conf</b> directory to make changes easier.</p>
+ <p>To change the setting for an individual JAR, see the
+ <a HREF="ejx.html">EJX Walkthrough</a> or the
+ <code>jboss.xml</code> DTD in the
+ <a HREF="dtds.html">DTDs Section</a>.</p>
+
+ <h2><a NAME="jndi">Using JNDI</a></h2>
+ <p>Your clients need to connect to the EJBs on the server via
+ JNDI. There are three ways to pass the JNDI configuration
+ information to the client. First, the client may include a
+ file named <code>jndi.properties</code> on its classpath. You
+ can find a default <code>jndi.properties</code> file in the
+ <b>conf</b> directory. If you look at it, each line is in
+ the form <i>parameter=value</i>. The second options is to
+ set System properties for the client runtime environment.
+ Those properties need to have the same names and values as the
+ entries in the <code>jndi.properties</code> file. You can set
+ System properties in your code, or on the java command line.
+ Finally, you can put the properties in a Hashtable object and
+ pass it into your <code>InitialContext</code> every time you
+ do the lookup. This is not recommended if you're only using
+ one JNDI server, since you'll have to repeat the settings once
+ per lookup. If the client uses EJBs or other resource on more
+ than one JNDI server at the same time, however, this is the way
+ you'll have to do it.</p>
+ <p>Here are the required properties for jBoss:</p>
+ <table BORDER="1">
+ <tr><th>property</th><th>value</th></tr>
+ <tr>
+ <td ALIGN="right">java.naming.factory.initial</td>
+ <td><code>org.jnp.interfaces.NamingContextFactory</code></td>
+ </tr>
+ <tr>
+ <td ALIGN="right">java.naming.provider.url</td>
+ <td>Server's host name, or host:port if you're using a port
+ other than the 1099 default</td>
+ </tr>
+ <tr>
+ <td ALIGN="right">java.naming.factory.url.pkgs</td>
+ <td><code>org.jboss.naming</code></td>
+ </tr>
+ </table>
+
+ <h3><a NAME="remote">Connecting to a Remote Server</a></h3>
+ <p>The default <code>jndi.properties</code> files specifies
+ <code>localhost</code> as the
+ <code>java.naming.provider.url</code>. This is suitable if
+ your client and server are on the same machine, but you must
+ change it to the host name of the server if you want to run
+ your client on a different machine. You will also need to
+ include the port number if you have changed the default
+ server port (see <a HREF="adv_config.html#ports">Changing
+ Default Port Assignments</a> in the
+ <a HREF="adv_config.html">Advanced Cofiguration</a>
+ section).</P>
+ <p>However, this alone only ensures that your client looks up
+ objects on the correct server. Once the client has created
+ a remote object, there is a different setting that controls
+ where the remote object looks to communicate with the server.
+ This setting also defaults to <code>localhost</code>, and must
+ be changed. But in this case, you need to change it on the
+ server side. To make this change, see
+ <a HREF="config.html#remote">Clients on Remote Machines</a>
+ in the <a HREF="config.html">Basic Configuration</a>
+ section.</p>
+
+ <h2><a NAME="libs">Required Client Libraries</a></h2>
+ <p>The client requires a number of JAR files, by default. You
+ may optionally choose to have the client download the required
+ files dynamically from the server, thereby reducing the number
+ of JAR files required for the client, or eliminating the
+ requirement altogether.</p>
+
+ <h3><a NAME="standard">Standard Libraries</a></h3>
+ <p>Here are the standard libraries your client will need. They
+ can all be found in the <b>client</b> directory. In addition,
+ your client will need the home interface, remote interface,
+ primary key, and any custom structures or helper classes
+ for any EJBs it uses. You may choose to distribute the same
+ EJB JAR you deploy in the server, but you may also distribute
+ a custom JAR without the EJB implementations, deployment
+ descriptors, etc.</p>
+ <table BORDER="1">
+ <tr><th>JAR Name</th><th>Contents</th><th>jBoss-Specific</th></tr>
+ <tr>
+ <td>jnp-client.jar</td>
+ <td>JNDI Client Implementation</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>jboss-client.jar</td>
+ <td>jBoss client code</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>jndi.jar (<b>JDK <= 1.2.2 Only!</b>)</td>
+ <td>JNDI Standard Extension (included in JDK 1.3+)</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>jta-spec1_0_1.jar</td>
+ <td>JTA 1.0.1 Standard Extension</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>ejb.jar</td>
+ <td>EJB 1.1 Standard Extension</td>
+ <td>No</td>
+ </tr>
+ </table>
+
+ <h3><a NAME="dynamic">Advanced Dynamic Loading</a></h3>
+ <p><i>This section is forthcoming.</i></p>
+
+ <h2><a NAME="application">Application Clients</a></h2>
+ <p>There are no special requirements for application clients.
+ If your application installs a security manager, make sure it
+ has network privileges to communicate with the server.</p>
+
+ <h2><a NAME="applet">Applet Clients</a></h2>
+ <p>Applets may be run natively in the JVM of the browser, or
+ via the Java Plug-In. In either case, you will most likely
+ need to sign your Applet to grant it the network, file, and/or
+ system property permissions it requires to configure JNDI and
+ communicate with the jBoss server. It may be possible to use
+ an unsigned applet, but we have not tried it.</p>
+
+ <h3><a NAME="browser">Browser Native</a></h2>
+ <p>Current browsers support some or all of JDK 1.1. Since that
+ is not a supported client environment for jBoss, you should
+ use the plug-in if at all possible. If you do decide to try
+ to use the native JVM, be aware that the security
+ configuration differs by browser, and a browser may or may not
+ support the permissions required.</p>
+
+ <h3><a NAME="plug-in">Java Plug-In</a></h2>
+ <p>The Java Plug-In is the recommended method of running jBoss
+ applet clients. You should sign your applet in order to
+ grant it the required security permissions. For signing
+ applets for the plug-in, you should seriously consider using
+ a DSA certificate (such as
+ <a HREF="http://www.thawte.com/certs/developer/sunjava12.html">Thawte</a>
+ provides) instead of an RSA certificate (such as
+ <a HREF="http://www.verisign.com/developer/index.html">Verisign</a>
+ provides). Though Sun's documentation claims that the
+ plug-in supports RSA certificates, in practice it does not seem
+ to.</p>
+ <p>When you sign an applet for the plug-in, it is granted all
+ security permissions, so you do not need to specify individual
+ settings. Additionally, all the required libraries will be
+ downloaded from the server, so no client software installation
+ is required. If you want to store libraries on the client to
+ provide faster startup, you are encouraged to use the caching
+ mechanism provided by the plug-in rather than attempting to
+ write the libraries to the local disk. The plug-in can cache
+ JARs separately from the browser cache, and update as you
+ direct. See the
+ <a
HREF="http://java.sun.com/products/plugin/1.3/docs/appletcaching.html">Plug-In Caching
Documentation</a>
+ for more details.</p>
+
+ <h2><a NAME="servlet">Servlet & JSP Clients</a></h2>
+ <p>Servlets and JSPs may use EJBs. There are two ways to install
+ a Servlet engine with jBoss. However, there is one common
+ requirement: Make sure that you install the jBoss libraries
+ and your EJB interface classes at the same level in your
+ Servlet engine. For example, do not install the jBoss
+ libraries as global libraries, but the EJB classes as local to
+ a specific web app or servlet context. You can either install
+ all at the server level, or all at the web app/context level,
+ and we recommend the latter.</p>
+ <p>The rest of this topic degenerates rapidly into technical
+ details. We would encourage you to use a Servlet engine that
+ is already supported in jBoss, such as Tomcat. In that case,
+ the configuration information presented in the
+ <a HREF="third_party.html">Third-Party Software</a> section
+ will resolve all the issues described below.</p>
+
+ <h3><a NAME="techie">Servlet Engine Integration: Technical Details</a></h2>
+ <p>As for the specific Servlet engine installation options, the
+ first option is to install the Servlet engine completely
+ separately from jBoss, even if they run on the same machine.
+ The performance is typically worse for this environment, but
+ it is easier to configure since the servlets can be treated as
+ any other client. Additionally, this may provide better
+ stability and/or security, since the Servlet engine and jBoss
+ communicate only over the network. The main issue to be
+ aware of in this case are the security settings on your
+ servlets - make sure they have network access to communicate
+ with the jBoss server.</p>
+ <p>The other way is to run jBoss and the Servlet engine in the
+ same JVM. This provides greater performance since it can avoid
+ networking operations, but is more difficult to configure, and
+ errors in the Servlet engine or jBoss could potentially
+ incapacitate both. In this case, you will have to make sure to
+ configure the ClassLoader for your servlets appropriately. Many
+ Servlet engines use a number of ClassLoaders, and it may be the
+ case that the ClassLoader that loads the EJB classes is not the
+ current one at the time of a request. You can often resolve this
+ be using the <code>Thread.setContextClassLoader</code> API call
+ before you attempt to work with EJBs.</p>
+ <p>Another related problem is that you would like the servlets and
+ EJBs to actually use the <i>same</i> ClassLoader. In the prior
+ example, you may have had different ClassLoaders on the servlet
+ side and the EJB side - the context class loader setting just
+ ensures that everything on the servlet side is consistant. If
+ you use the same ClassLoader for servlets and EJBs, you can
+ replace all network calls with VM local calls, and reduce the
+ need for serialization. This may be difficult to achieve,
+ however, since either jBoss must dig into the Servlet engine and
+ grab the appropriate ClassLoader for an EJB JAR, or vice
+ versa.</p>
+
+ <h2><a NAME="corba">CORBA Clients</a></h2>
+ <p>jBoss does not currently support IIOP, so you will not be able
+ to interact directly with EJBs via CORBA. However, you could
+ certainly create a CORBA service that used the normal JNDI
+ mechanisms to communicate with EJBs on jBoss, and then make
+ that service available to CORBA clients.</p>
+
+ <h2><a NAME="ejb">EJB Clients</a></h2>
+ <p>EJBs can act as clients to other EJBs, whether on the same
+ server or not. All you need to do is declare an EJB reference
+ in your EJB 1.1 deployment descriptor (see the
+ <a HREF="deploying.html#ejb11">EJB 1.1 Deployment Descriptor</a>),
+ and the point it to the correct home interface for the referenced
+ EJB in the jBoss deployment descriptor (see the
+ <a HREF="deploying.html#jboss">jBoss Deployment Descriptor</a>).
+ Then you just look up the other EJB home using the
+ <code>java:comp/env</code> namespace, and go from there.</p>
+ <p>Of course, you will still need the home and remote interfaces for
+ the referenced EJB to be available to the referencing EJB - if
+ they are not packaged together in the same EJB JAR. You can
+ either add the classes for the referenced EJB to the JAR of the
+ referencing EJB, or if they are deployed together you can add a
+ classpath entry to the manifest file for the referencing EJB's JAR.
+ And finally, if the referenced EJB is not in a jBoss server, you
+ may need additional JNDI configuration, and you may need client
+ JARs for the other server to be available to jBoss. This is not
+ likely to work if the servers support different versions of the
+ EJB specification.</p>
</body>
</html>
1.3 +4 -1 jbossweb/manual/deploying.html
Index: deploying.html
===================================================================
RCS file: /products/cvs/ejboss/jbossweb/manual/deploying.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- deploying.html 2000/09/19 14:28:35 1.2
+++ deploying.html 2000/10/02 17:43:26 1.3
@@ -87,7 +87,10 @@
<ul>
<li>The JNDI name for the EJBs in the JAR</li>
<li>Any data sources or other resources used by the EJBs in the
- JAR</li>
+ JAR (declared in <code>ejb-jar.xml</code>)</li>
+ <li>How to resolve EJB references (declared in
+ <code>ejb-jar.xml</code>) when the EJBs in this JAR refer to
+ other EJBs (in this JAR or elsewhere)</li>
<li>The RMI configuration for each EJB in the JAR, which
determines the client JDK version compatibility</li>
<li>The instance pool characteristics for each EJB in the JAR</li>
1.9 +14 -13 jbossweb/manual/index.html
Index: index.html
===================================================================
RCS file: /products/cvs/ejboss/jbossweb/manual/index.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- index.html 2000/09/29 20:54:25 1.8
+++ index.html 2000/10/02 17:43:26 1.9
@@ -102,19 +102,20 @@
<p CLASS="tc2">Web Administration</p>
<p CLASS="tc2">JMX Client Administration</p>
<p CLASS="tc1"><a CLASS="plain" HREF="clients.html">jBoss Clients</a></p>
- <p CLASS="tc2">Supported Java Versions</p>
- <p CLASS="tc2">Using JNDI</p>
- <p CLASS="tc3">Connecting to a Remote Server</p>
- <p CLASS="tc2">Required Client Libraries</p>
- <p CLASS="tc3">Standard Libraries</p>
- <p CLASS="tc3">Advanced Dynamic Loading</p>
- <p CLASS="tc2">Application Clients</p>
- <p CLASS="tc2">Applet Clients</p>
- <p CLASS="tc3">Browser Native</p>
- <p CLASS="tc3">Java Plug-In</p>
- <p CLASS="tc2">Servlet & JSP Clients</p>
- <p CLASS="tc2">CORBA Clients</p>
- <p CLASS="tc2">EJB Clients</p>
+ <p CLASS="tc2"><a CLASS="plain" HREF="clients.html#jdk">Supported Java
Versions</a></p>
+ <p CLASS="tc2"><a CLASS="plain" HREF="clients.html#jndi">Using JNDI</a></p>
+ <p CLASS="tc3"><a CLASS="plain" HREF="clients.html#remote">Connecting to
a Remote Server</a></p>
+ <p CLASS="tc2"><a CLASS="plain" HREF="clients.html#libs">Required Client
Libraries</a></p>
+ <p CLASS="tc3"><a CLASS="plain" HREF="clients.html#standard">Standard
Libraries</a></p>
+ <p CLASS="tc3"><a CLASS="plain" HREF="clients.html#dynamic">Advanced
Dynamic Loading</a></p>
+ <p CLASS="tc2"><a CLASS="plain" HREF="clients.html#application">Application
Clients</a></p>
+ <p CLASS="tc2"><a CLASS="plain" HREF="clients.html#applet">Applet
Clients</a></p>
+ <p CLASS="tc3"><a CLASS="plain" HREF="clients.html#browser">Browser
Native</a></p>
+ <p CLASS="tc3"><a CLASS="plain" HREF="clients.html#plug-in">Java
Plug-In</a></p>
+ <p CLASS="tc2"><a CLASS="plain" HREF="clients.html#servlet">Servlet & JSP
Clients</a></p>
+ <p CLASS="tc3"><a CLASS="plain" HREF="clients.html#techie">Servlet Engine
Integration: Technical Details</a></p>
+ <p CLASS="tc2"><a CLASS="plain" HREF="clients.html#corba">CORBA
Clients</a></p>
+ <p CLASS="tc2"><a CLASS="plain" HREF="clients.html#ejb">EJB Clients</a></p>
<p CLASS="tc1"><a CLASS="plain" HREF="third_party.html">Third-Party
Software</a></p>
<p CLASS="tc2">About JVM Integration</p>
<p CLASS="tc2">J2EE</p>
1.2 +4 -0 jbossweb/manual/manual.css
Index: manual.css
===================================================================
RCS file: /products/cvs/ejboss/jbossweb/manual/manual.css,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- manual.css 2000/09/14 18:28:37 1.1
+++ manual.css 2000/10/02 17:43:26 1.2
@@ -10,6 +10,10 @@
font-family: Verdana, Arial, Helvetica, sans-serif;
}
+code {
+ font-family: Courier New, Courier, sans-serif;
+ }
+
.tc1 {
margin-bottom: 0;
margin-left: 0.1in;
1.9 +4 -2 jbossweb/manual/warning.html
Index: warning.html
===================================================================
RCS file: /products/cvs/ejboss/jbossweb/manual/warning.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- warning.html 2000/09/30 13:58:28 1.8
+++ warning.html 2000/10/02 17:43:27 1.9
@@ -90,10 +90,12 @@
</li>
<li>jBoss Clients
<ul>
- <li>This section must be written</li>
+ <li>Confirm host:port syntax of jndi.properties for
+ non-default JNP port settings</li>
+ <li>Write advanced dynamic loading section</li>
</ul>
</li>
- <li>Entending jBoss
+ <li>Extending jBoss
<ul>
<li>This section must be written</li>
</ul>
