-The target audience for this guide is the JOnAS server administrator.
- -JOnAS provides the following two tools for performing some administration -tasks on a running JOnAS Server:
-jonas admin, a
- command line toolJonasAdmin, a
- graphical tool based on the Struts framework and the JMX technology
-
- These tools also allow administration of several JOnAS Servers. Each JOnAS
-Server is identified by a name, which is the value of the -n
-option used in the jonas start command (the default name is
-jonas).
jonas admin is described in the JOnAS -Commands chapter.
- -This chapter provides information about installing, configuring, and using -the JonasAdmin administration console.
- -JonasAdmin is the new administration tool for JOnAS and replaces the -deprecated Jadmin tool.
- -JonasAdmin was developed using the Struts framework; it uses -standard technologies such as Java Servlets and JavaServer Pages. JonasAdmin -is more ergonomic than Jadmin and provides integrated administration -facilities for a Tomcat server running embedded in JOnAS.
- -Designed as a web application, JonasAdmin is packed in a WAR and installed
-under the JONAS_ROOT/webapps/autoload/ directory. This WAR can
-be installed in JONAS_BASE/webapps/autoload if a JONAS_BASE
-variable has been defined in the environment. When installed in the
-autoload directory, JonasAdmin is deployed when starting the
-JOnAS server, thus the administration console is automatically accessible.
As with any web application, JonasAdmin requires a servlet server to be
-installed. Additionally, the JOnAS server running JonasAdmin must have the
-web container service present in the list of services defined in the
-jonas.properties configuration file.
When accessing JonasAdmin, the administrator must provide identification
-and authentication.
-The jonas-realm.xml configuration file contains a memory realm
-definition named memrlm_1, which is referenced in both
-server.xml (for Tomcat) and jetty.xml (for Jetty) configuration files. The
-default user name (jonas) and
-password (jonas) corresponding to the admin
-role can be modified here.
-
Once started, JonasAdmin can administer the JOnAS server in which it is
-running, as well as other JOnAS servers with which it shares the same
-registry. Typically, this is used to administer JOnAS servers running without
-the WEB container service.
-Note that the administered JOnAS servers can be running on the same host or
-on different hosts. Also, if Tomcat is used as the WEB container service
-implementation, it can be administered using JonasAdmin.
Ensure that the web service is listed in the
-jonas.services property in the jonas.properties
-configuration file. If you are not using a jonas-tomcat or jonas-jetty
-package, depending on the Servlet container being used, the
-CATALINA_HOME or the JETTY_HOME environment
-variable must have been previously set. Note that when running the Servlet
-container on top of Unix, the DISPLAY environment variable must
-be set in order to use the JOnAS server monitoring feature of JonasAdmin.
Once JOnAS is launched, JonasAdmin must be loaded if it was not installed
-in the autoload directory. The administration console is
-accessible at the URL:
-http://<hostname>:<portnumber>/jonasAdmin/
-using any web browser.
<hostname> is the name of the host where the Servlet -container is running and <portnumber> is the http port number -(default is 9000).
- -After logging in, the left-hand frame in the Welcome page displays the
-management tree associated with the JOnAS server running JonasAdmin.
-Starting with JOnAS 4.6, the management tree's root is Domain, which
-corresponds to the new domain management facilities.
-
In the image below, JonasAdmin is running on the master server named jonas
-within a domain also named jonas. It is immediately apparent that this is a
-master server, as we have a Deployment sub-tree under the Domain
-root node.
-
-The management tree in this figure allows access to the following main -management facilities:
-Displays general information about the administered JOnAS server, -including the JMX server and the WEB server, and provides the capability of -listing the content of the Registry.
- -Presents memory usage, a count of the threads created by JOnAS, and other -monitoring information concerning managed services and resources.
- -Allows the administrator to configure the JOnAS Logging system. -Additionally, if Tomcat is used as the WEB container service implementation, -it allows creation of new access log valves.
- -This management facility relates to the integration of Tomcat management
-in JonasAdmin.
-It currently presents connectors defined in the Tomcat configuration and
-allows for the creation of new HTTP, HTTPS, or AJP connectors.
-Note that the Protocols sub-tree is not presented if Jetty is
-used as the WEB container service implementation.
All the active services have a corresponding sub-tree in the
-Services tree.
Managing the various container services consists of presenting information -about the components deployed in these containers. New components can be -deployed using the dynamic deployment facilities presented in the next -section.
-
-Creation of a new context for WEB components to be deployed in the Tomcat server
-is deprecated since JOnAS 4.6 (the New web application button is
-removed).
-
Similarly, the services that allow management of the different types of
-resources (DataSources, Resource Adapters, Jms and Mail resources) also
-provide information about the resources being deployed. Additionally,
-deployed resources (DataSources or MailFactories) can be reconfigured and
-their new configuration made persistent by using a Save
-button.
The transaction service management allows reconfiguration (possibly -persistent) and presents monitoring information about transactions managed by -JOnAS.
- -A very useful management operation is the capability of loading
-stand-alone J2EE components (JAR, WAR, RAR packages) or J2EE applications
-(EAR packages) in the administered server using the Deployment
-sub-tree.
-
-The administrator's task is facilitated by the display of the list of
-deployable modules, the list of deployed modules, and the capability of
-transferring modules from one list to another (which corresponds to
-deploy/undeploy operations.
-
-The deployable modules are files installed in directories specific to their type. For example, the
-deployable JARs are un-deployed JARs installed in
-JONAS_BASE/ejbjars/ or in a
-JONAS_BASE/ejbjars/autoload/ directory.
-
-The Deployment sub-tree also allows a J2EE package to be uploaded from
-the local file system to the corresponding directory of the administered server
-(install operation), and the opposite remove operation.
-
Resources sub-tree provides the capability of loading or
-creating new resources managed by the active services. For example, if the
-JMS service is running, the JMS sub-tree in Resources presents
-the existing JMS destinations (Topics and Queues), and allows the removal of
-unused destinations and the creation of new JMS destinations.Save
-button, the JOnAS configuration file is updated. As in the JMS service
-example, the removed topics are deleted from the list assigned to the
-jonas.service.jms.topics property and the newly created topics
-are added to this list.
-
-Security sub-tree presents existing security realms and
-allows the creation of new realms of different types: memory, datasource, and
-ldap realms.
-
-
-First recall that domain management functions are accessible only when JonasAdmin
-is deployed on a master server. The Domain tree contains only one
-Server sub-tree, the currently administered server, which is initially
-the server hosting JonasAdmin.
-Domain management principal function is to present the domain topology: list all the servers and clusters -belonging to the domain. It also allows modification of the domain topology by adding new servers and clusters -to the domain, removing servers and moving servers to/from clusters.
--In JOnAS 4.6 there is no cluster support, and the domain topology cannot be modified. The servers presented as belonging -to the domain are those that have been started with their discovery service enabled.
-
-In JOnAS 4.7, domain management page also presents servers that are not yet started but are specified as
-belonging to the domain in the new configuration file named domain.xml.
-Also, a server can be added to the domain when it has been started without having the discovery service enabled.
-
-An essential domain management function is that the administrator can switch from the master to any of the
-other servers in the domain. Currently, JonasAdmin allows only one category of global domain level management
-operation, the deployment operation. Using any other management operation requires switching
-to the server to be administered.
Domain level deployment allows for deploying one or more J2EE packages (JARs, WARs, RARs or EARs), which
-are installed in the corresponding master directory (ejbjars, webaps, rars or apps), into any running server in the domain.
-A deployment operation target may be a server but also a cluster. In this case, the deployment
-operation addresses all the running servers in the cluster, including servers in the embedded clusters, if any.
-
-The deploy operation may have three semantics:
-
Upload and Remove operations
-are only related to the master server itself.
-
-
-Save operation is
-related to a service or a resource reconfiguration. For example, the
-administrator can reconfigure a service and a resource, but choose to save
-only the new resource configuration.Save operation is global to all configuration
-changes that have been performed. For example, if a new HTTP connector is
-reconfigured and a new context created for a web application, both
-configuration changes are saved when using the Save
-button.
-
-
--The MEJB component exposes the managed objects within the JOnAS -platform as JMX manageable resources. It is packed in an ejb-jar -file installed in the $JONAS_ROOT/ejbjars/autoload directory, -and therefor it is loaded at server start-up.
-
-The MEJB component is registered under the name
-java:comp/env/ejb/MEJB.
-The current implementation allows access only to the manageable -resources within the current server (the server containing the -MEJB's container).
-
-The JOnAS distribution was enriched with a new example called
-j2eemanagement, which shows how the MEJB can be used.
-You can find details about this management application in
-$JONAS_ROOT/j2eemanagement/README file.
CMI is the protocol cluster for JOnAS ensuring:
-
CMI can be enabled in JOnAS by:
-CMI brings its own registry for implementing the jndi replication. Each -CMI registry instance over the cluster contains two areas:
-When an object is registered in the registry, the routing to the local or -global area is done according to:
-The entries of the distributed area are lists providing the ability, for -example, to gather several stubs for the the same jndi-name and thus to -return a stubs list.
- -CMI relies on JGroups group-communication protocol for ensuring the global -registry replication. The parameters are gathered in the:
-
All the members of a cluster share the same JGroups configuration.
- -If several cluster partitions are required over a single LAN, several -JGroups configurations must be configured with different values for the -following parameters:
-When a new node appears in the cluster, its registry content is -synchronized automatically.
- -When a node disappears, JGroups notifies the other's member of the node -leaving and the registry entries related to this node are removed.
- -On the client side, the high availability of the registry is provided by -the capability to set several JOnAS instances in the registry url. At the -lookup time, the client chooses (round-robin algorithm) one of the available -servers to get the home stub. If the server fails, the request is sent to -another server. The CMI url registry is specified in the -$JONAS_BASE/conf/carol.properties file using the following syntax:
-carol.cmi.url=cmi://server1:port1[,server2:port2...]- -
Load-balancing and fail-over on the client side are provided through -cluster-aware stubs. These stubs are generated on the fly through ASM and -rely on:
-
The CMI cluster stub handles a cluster map on the client side. The CMI -cluster stub is created:
-In these two cases, the call gets a stubs list from the global registry -and the CMI cluster stub updates the local cluster map. Afterwards, the local -cluster map can be updated dynamically during the invocation of the business methods calls (through the HA interceptors) when a new view is detected in -the cluster.
- -If a communication error with a server occurs during a remote call -invocation, the server is removed from the cluster map.
- -CMI classes are generated by GenIC when compiling with the protocol CMI. -They are built from the velocity templates located in -$JONAS_ROOT/templates/genic directory. By default the templates used are:
-The templates inherit the org.objectweb.carol.cmi.Distributor class and -contain the following methods:
-
- public StubData choose(Method method, Object[] parameters) throws NoServerException {
-
- Set stubs = getCurrentState();
- if (lastSet != stubs) {
- lastSet = stubs;
- rr.update(stubs);
- }
-
- return rr.get();
- }
-
-
- protected static boolean mustFailover(Exception ex) {
- if (ex instanceof UnmarshalException) {
- Throwable cause = ((UnmarshalException) ex).getCause();
- if (( cause instanceof EOFException) ||
- (cause instanceof SocketException)) {
- return true;
- }
- }
-
- if ((ex instanceof ConnectException) ||
- (ex instanceof ConnectIOException) ||
- (ex instanceof NoSuchObjectException)) {
- return true;
- }
- return false;
- }
-
-
- The user has the ability to customize the load-balancing and fail-over -logic for each EJB by specifying the velocity template to use in the JOnAS- -specific descriptor on deployment of the ejb-jar file. The XML elements -are:
-<cluster-home-distributor>MyHomeDistributor.vm</cluster-home-distributor>-
<cluster-remote-distributor>MyRemoteDistributor.vm</cluster-remote-distributor>- -
If not set, the default velocity templates are used.
- -If set with the value 'disabled', the CMI classes are not generated and -the EJB will not be distributed.
- -If set with a file name, this file must be located in the -$JONAS_ROOT/templates/genic directory.
- -The 'cluster-home-distributor' element is valid for the SSB, SFSB and -EB.
- -The 'cluster-remote-distributor' element is valid for the SSB.
- -Stateful session beans (SFSBs) can be replicated since JOnAS 4.7 in order -to provide high availability in the case of failures in clustered environments. -A new service called High Availability (HA) has been included in JOnAS to -provide replication mechanishms. JOnAS HA also requires the cluster -method invocation (CMI) protocol.
- -Compared to JOnAS 4.7, JOnAS 4.8 implements a new replication algorithm -based on a horizontal replication approach. The algorithm improves the -algorithm implemented for JOnAS 4.7 with the following enhancements:
- -JOnAS implements an update-everywhere replication protocol according to -the database replication terminology (See the J. Gray et al.'s paper ''The -dangers of replication and a solution'' in proceedings of the ACM SIGMOD 96's -conference, Canada). In this protocol, a client can connect to any server. -When the client calls the create() method on the SFSB's Home interface, the -server the client connects to is selected following a round-robin scheme. All -the requests from the client to the SFSB will be processed by this server -until the client calls the remove() method on the remote interface. The rest -of the servers will act as backups for that client. Before sending the -response to the client, the SFSB's state is sent to the backups.
- -If the server fails, another server among the backups will be selected to -serve the client requests, first restoring the current state of the SFSBs -from the state information stored in the HA local service. From this point -on, this server will receive the new client requests.
- -The supported replication scenarios are shown in the following figure:
- -
The horizontal approach aims to guarantee that the transactions are kept -consistent when a fail-over occurs. They are either aborted or restored -for ensuring the exactly-once semantics. During a fail-over, the new primary -uses a special table in the database for storing the transaction identifier -and enabling to find out if the transaction was committed or not. -
The High Availability (HA) service is required in JOnAS in order to -replicate SFSBs. The HA service must be included in the list of available -services in JOnAS. This is done in the jonas.properties file placed in -$JONAS_BASE/conf.
-... -jonas.services registry,jmx,jtm,db,dbm,security,resource,ejb,ws,web,ear,ha -...- -
The HA service must also be configured in the jonas.properties file:
-... -jonas.service.ha.class org.objectweb.jonas.ha.HaServiceImpl -jonas.service.ha.gcl jgroups -... -- -
The HA service uses JGroups as a group communication layer (GCL). JGroups -behavior is specified by means of a stack of properties configured through an -XML file (See JGroups documentation for more -information: http://www.jgroups.org). The default configuration of the HA -service uses the $JONAS_BASE/conf/jgroups-ha.xml file and the sfsb-rep group name. The HA -service can be told to use a particular stack configuration or a particular group name by modifying the following -lines in jonas.properties:
-... -jonas.service.ha.jgroups.conf jgroups-ha.xml -jonas.service.ha.jgroups.groupname jonas-rep -...-Finally, the CMI protocol must be specified in the carol.properties file in -$JONAS_BASE/conf: -
... -carol.protocols=cmi... -...- -
The new horizontal replication algorithm uses a database table -to keep track of current running transactions. This table is accessed from the new -elected node during fail-over to detect whether or not the current transaction committed at -the former local node, ensuring exactly-once semantics. -The table contains only one column: the transaction identifier (txid).
-In JOnAS 4.8 this table must be created manually with the following SQL command:
-create TABLE ha_transactions (txid varchar(60));-
This table should be located preferably in the database used by the replicated -application, but it is not mandatory. If the table is not created in the database -used by the replicated application, it is necessary to configure a new datasource -for the database that contains this transaction table. This datasource must be -configured to use the serializable transaction isolation level.
- -The database that holds the transaction table is accessed by the replication service with -the JNDI name configured in jonas.properties.
-... -jonas.service.ha.datasource tx_table_ds -...- -
... -jonas.service.ha.timeout 600 -...- -
In order to configure an application for replication, the <cluster-replicated/> element must be added to the bean definition of every -bean requiring high availability in the jonas-ejb-jar.xml deployment -descriptor file. This element can have two possible -values: true or false (default value). In addition, if the programmer wants -to change the behavior of the CMI stubs (e.g., the server selection policy), -it is possible to specify different distributor implementations by means of -<cluster-home-distributor/> and <cluster-remote-distributor/> -elements. In this case, the value corresponds to the .vm file that implements -the distributor in its home and remote parts respectively. If the -<cluster-replicated/> element is present without the -<cluster-*-distributor/> elements, the default values are used -(ClusterHomeSFSBRepDistributor.vm and ClusterRemoteSFSBRepDistributor.vm).
- -The following is an example description for a replicated SFSB in -jonas-ejb-jar.xml file:
-... -<jonas-session> - <ejb-name>DummySFSB</ejb-name> - <jndi-name>DummySFSB</jndi-name> - ... - <cluster-replicated>true</cluster-replicated> - <cluster-home-distributor>Dummy_HomeDistributor.vm</cluster-home-distributor> - <cluster-remote-distributor>Dummy_RemoteDistributor.vm</cluster-remote-distributor> -</jonas-session> -...- -
The <cluster-replicated/> element can also be set in the SSB or EB for -
Note: When set in the SSB, the mechanism inhibits the load-balancing at the remote -interface. After the home create() method call, all the requests are sent to the same -instance.
- -The lock policy for the Entity Beans in a replicated application must be configured -as database in the jonas-ejb-jar.xml deployment descriptor file.
-The following is an example description for a replicated EB in the jonas-ejb-jar.xml:
-... -<jonas-entity> - <ejb-name>MyEntitySLR</ejb-name> - <jndi-name>MyEntityHome</jndi-name> - <cluster-replicated>true</cluster-replicated> - <shared>true</shared> - <jdbc-mapping> - <jndi-name>example_ds</jndi-name> - </jdbc-mapping> - <lock-policy>database</lock-policy> -</jonas-entity> -...- -
The datasources used by replicated applications must be configured to use the -serializable transaction isolation level.
-The following is an example for a datasource configuration file for the Postgres DBMS:
-... -datasource.name example_ds -datasource.url jdbc:postgresql://xxx.xxx.xxx.xxx:xxxx/database -datasource.classname org.postgresql.Driver -datasource.username jonas -datasource.password -datasource.mapper rdb.postgres -datasource.isolationlevel serializable -...- -
Finally, when compiling the application that includes the replicated -beans, the CMI protocol must be specified in order to generate the classes -that include the replication logic.
- -NOTE: It is recomended to not change the Datasource once the HA service - is running.
The target audience for this guide is the application deployer.
- -The content of this guide is the following:
-This guide assumes that the Enterprise Bean provider followed the
-Enterprise Beans Programmer's Guide and packaged the beans's classes together
-with the deployment descriptors in a ejb-jar file. To deploy un-packed
-Enterprise Beans, refer to Configuring EJB
-Container service.
-
To deploy the Enterprise Beans in JOnAS, the deployer must add the
-interposition classes interfacing the EJB components with the services
-provided by the JOnAS application server.
-The GenIC tool supplied in the JOnAS
-distribution provides the capability of generating interposition classes and
-updating the ejb-jar file.
-The application deployer may also need to customize the deployment
-descriptors in order to adapt it to a specific operational environment. This
-must be done before using GenIC.
The deployer may choose to deploy the Enterprise Beans as stand-alone
-application components, in which case the ejb-jar must be installed in the
-$JONAS_ROOT/ejbjars directory. The deployer may also choose to
-include them in war or ear packaging, which is presented in the following
-sections.
$JONAS_ROOT/webapps directory, for war files$JONAS_ROOT/apps directory, for ear filesFor this example, it is assumed that a user wants to customize the
-deployment of the AccountImpl bean in the JOnAS example
-examples/src/eb by
-changing the name of the database table used for the persistence of the
-AccountImpl.
The current directory is $JONAS_ROOT/examples/src/eb. The
-user will do the following:
jonas-ejb-jar.xml and modify the value of the
- <jdbc-table-name> element included in the
- <jdbc-mapping> element corresponding to
- AccountImpl entity..java files present in this
- directory: javac -d ../../classes Account.java
- AccountImplBean.java AccountExplBean.java AccountHome.java
- ClientAccount.javaejb-jar.jar with all the
- corresponding classes and the two deployment descriptors:-mkdir -p ../../classes/META-INF -cp ejb-jar.xml ../../classes/META-INF/ejb-jar.xml -cp jonas-ejb-jar.xml ../../classes/META-INF/jonas-ejb-jar.xml -cd ../../classes -jar cvf eb/ejb-jar.jar META-INF/ejb-jar.xml META-INF/jonas-ejb-jar.xml - eb/Account.class eb/AccountExplBean.class eb/AccountHome.class eb/AccountImplBean.class --
ejb-jar.jar file with the
- interposition classes:
- GenIC -d ../../classes ejb-jar.jar
$JONAS_ROOT/ejbjars
- directory:
- cp ../../classes/eb/ejb-jar.jar $JONAS_ROOT/ejbjars/ejb-jar.jar
jonas start
-
-The steps just described for building the new ejb-jar.jar
-file explain the deployment process. It is generally implemented by an ANT
-build script.
If Apache ANT is installed on your machine, type ant
-install in the $JONAS_ROOT/examples/src directory to build
-and install all ejb-jar.jar files for the examples.
-To write a build.xml file for ANT, use the ejbjar
-task, which is one of the optional EJB tasks defined
-in ANT. The ejbjar task contains a nested element called
-jonas, which implements the deployment process described above
-(interposition classes generation and EJB-JAR file update).
-Generally, the latest version of the EJB task containing an updated
-implementation of the jonas nested element is provided with
-JOnAS, in $JONAS_ROOT/lib/common/ow_jonas_ant.jar. Click here
-for the documentation corresponding
-to this new version of the jonas nested element.
-As an example, this code snippet is taken from the
-$JONAS_ROOT/examples/src/alarm/build.xml:
-
- <!-- ejbjar task -->
- <taskdef name="ejbjar"
- classname="org.objectweb.jonas.ant.EjbJar"
- classpath="${jonas.root}/lib/common/ow_jonas_ant.jar" />
-
- <!-- Deploying ejbjars via ejbjar task -->
- <target name="jonasejbjar"
- description="Build and deploy the ejb-jar file"
- depends="compile" >
- <ejbjar basejarname="alarm"
- srcdir="${classes.dir}"
- descriptordir="${src.dir}/beans/org/objectweb/alarm/beans"
- dependency="full">
- <include name="**/alarm.xml"/>
- <support dir="${classes.dir}">
- <include name="**/ViewProxy.class"/>
- </support>
- <jonas destdir="${dist.ejbjars.dir}"
- jonasroot="${jonas.root}"
- protocols="${protocols.names}" />
- </ejbjar>
- </target>
-
-
-
-Before deploying a web application in the JOnAS application server, first
-package its components in a war file as explained in the WAR packaging guide.
-For Apache ANT, refer to the target war in the
-$JONAS_ROOT/examples/earsample/build.xml file.
Next, install the war file into the
-$JONAS_ROOT/webapps directory.
-Note: Be aware that the war file must not be installed in the
-$CATALINA_HOME/webapps directory.
Then, check the configuration: before running the web application;
-check that the web service is present in the
-jonas.services property. The ejb service may also be
-needed if the Web application uses enterprise beans.
-The name of the war file can be added in the
-jonas.service.web.descriptors section.
Finally, run the application Server:
- jonas start
The web components are deployed in a web container created during the
-startup. If the war file was not added in the
-jonas.service.web.descriptors list, the web components can be
-dynamically deployed using the jonas admin command or
-JonasAdmin tool.
Before deploying a J2EE application in the JOnAS application server, first
-package its components in an ear file as explained in the EAR packaging
-guide.
-For Apache ANT, refer to the target ear in the
-$JONAS_ROOT/examples/earsample/build.xml file.
Next, install the ear file into the $JONAS_ROOT/apps
-directory.
Then, check the configuration: before running the application,
-check that the ejb, web and ear services are
-present in the jonas.services property.
-The name of the ear file can be added in the
-jonas.service.ear.descriptors section.
Finally, run the application Server:
- jonas start
The application components are deployed in EJB and web containers created
-during the startup. If the ear file was not added in the
-jonas.service.ear.descriptors list, the application components
-can be dynamically deployed using the jonas admin command or
-JonasAdmin tool.
The content of this guide is the following:
-This guide is intended for JOnAS administrators responsible for the configuration - and administration of JOnAS servers running within a management domain. -
- -A JOnAS management domain is composed of a set of JOnAS servers that are running under the same - management authority. All the servers in the domain must have a distinct server name and - a common domain name. -
-The servers in a domain can be administered by a management application running on a server - playing the role of administrator or master. The managed servers play the role of slaves. - Note that it is possible to have several masters in a domain. Also note that default configuration - corresponds to a slave server running without the discovery service (the role of this service is - described below and its configuration here). -
-- Typically, when deploying the JonasAdmin application on a slave, the administrator can manage only - the server on which the application is running. When deploying JonasAdmin on a master server, - the administrator can manage all the known servers in the domain: -
- Cluster management facilities was introduced in JOnAS 4.7. - A cluster is a group of servers having common properties within a domain. A cluster may be the target of a - domain level management operation - currently applications and J2EE modules deployment only. -
-- The domain topology (servers and clusters composing the domain) can be defined using a new domain.xml - configuration file. Also, servers and clusters may be dynamically added and removed to the domain via JonasAdmin. -
-- Starting with JOnAS 4.8, domain and cluster management is enhanced with monitoring functions available in - JonasAdmin. As in the previous version, clusters may be created by an administrator in a static (via domain.xml) - or dynamic (via JonasAdmin) way. These clusters are now called logical cluster. A new class of clusters - is supported in the current version, the physical clusters that are detected automatically by the management - infrastructure. Several types of physical clusters are supported: Mod JK clusters, Tomcat clusters, CMI clusters, etc. - All the members of a type of physical cluster share specific properties which depend on the cluster type, e.g., all - the members of a CMI cluster have the same JGroups configuration. Note that a given JOnAS instance may belong to - several physical and logical clusters. -
-- An important domain level administration operation introduced in JOnAS 4.8, is the possiblity to start/stop - the managed servers via a so called cluster daemon. - Cluster daemons can be defined and associated - to servers using the domain.xml configuration file. A cluster daemon has to be collocalized (located on the same - machine) with the servers it controls. -
- -Basically, domain management in JOnAS relies on JSR 160 specification. When a JOnAS server is started, - it creates at least one JSR 160 connector server as explained in - JSR 160 support in JOnAS. -
-- A connector server makes it possible for a JMX remote API client to access and manage the MBeans exposed - through the MBean server running in a remote JVM. In order to establish a connection, the remote client - needs to know the address of the connector server. JSR 160 does not provide any specific API that would - make it possible for a client to find the address of a connector server. The standard suggests using - existing discovery and lookup infrastructures, for instance, JNDI API with an LDAP back end. -
-- A new service added to JOnAS, the Discovery Service, allows JOnAS servers running over - a LAN within the same management domain to communicate to each other the connector-server addresses they create - at start-up. All the servers in the domain having the discovery service in the services list, will - publish their connector-server address at start-up. The goal is to allow master servers to - discover which servers are running in their domain, and to establish connections allowing them to remotely - manage the slave servers by a management application deployed on a master server. -
-- Starting with JOnAS 4.7, a server can be added to a domain via a management operation, thus allowing servers which - cannot use the multicast-based discovery service to join a management domain. -
-- The current discovery service implementation is based on MBeans (called discovery MBeans) which use: -
J2EEDomain MBean.
-
- The J2EEDomain MBean has the following JMX ObjectName:
-
- domainName:j2eeType=J2EEDomain,name=domainName -- Where domainName is the name of the domain. - -
- A J2EEDomain MBean contains several management attributes and operations related to servers management
- in a domain:
-
J2EEDomain is registered in a master server's MBean server, the servers
- attribute keeps the list of the servers known in the domain. Otherwise, it contains only one element corresponding to itself.
- The elements in the servers list are Strings representing J2EEServer ObjectNames
- associated to the running servers. By iterating over the servers
- list, a management application can determine the name of the servers in the domain.
- MBeanServerConnection object using one of the connector-server addresses corresponding to that server
- (see the j2eemanagement sample).
- -
-
- Starting with JOnAS 4.7, the J2EEDomain MBean was enriched in order to support adding/removing a server to/from the domain,
- creating a cluster in the domain, listing the clusters in a domain.
-
- The following is a list of some of the new management attributes and operations exposed by a J2EEDomain MBean:
-
J2EEDomain ObjectNames
- associated to the clusters created in this domain
- (or in this cluster if the current J2EEDomain MBean is associated to a cluster).
- In JOnAS 4.7, clusters are implemented as "sub-domains", they have associated J2EEDomain
- type MBeans. For example, if a cluster named clust is created in the domain named
- domainName, it has an associated MBean with the following JMX ObjectName:
-
- domainName:j2eeType=J2EEDomain,name=domainName,clusterName=clust,parentClusterName=domainName -- - - -
- An important re-engineering of domain management mechanisms was conducted in JOnAS 4.8 to support
- cluster and domain monitoring. Clusters aren't implemented as sub-domains anymore; there is only
- one J2EEDomain MBean registered in the master's MBean server. Another important point
- is that the servers' state is no longer accessible in the J2EEDomain MBean (getServerState(serverName)
- operation doesn't exist anymore). On the other hand, new MBeans were created:
-
ServerProxy MBeans. For every server known in the domain, a ServerProxy MBean is created with the
- following JMX ObjectName:
- - domainName:type=ServerProxy,name=serverName -- It contains a
State attribute which gives the server state as known by the master, and
- a set of monitoring information like memory usage, threads, transactions, etc. which are periodically
- updated. The servers may be in one of the following states:
- MBeanServerConnection could
- not be established, or it doesn't work anymore) jonas stop
- command (if the server has enabled its discovery service), or if the server was stopped
- using the remote control mechanisms (via the cluster daemon). Cluster MBeans. For every cluster created in the domain, a LogicalCluster
- MBean is created with the following JMX ObjectName:
- - domainName:type=LogicalCluster,name=clusterName --
- The master may have registered other types of cluster MBeans which correspond to physical clusters. - They are automatically created by the management system if managed servers are identified as - being members of supported physical cluster types. -
- A cluster MBean contains aState attribute and a member's list.
- A cluster may be in one of the following states,
- which depends on the state of its members.
- ClusterMember MBeans. A member MBean's role is to make the link between a cluster MBean and
- the ServerProxy MBean
- corresponding to the server which belongs to that cluster. Any member MBean has a ServerProxy attribute
- equal to the corresponding ServerProxy MBean OBJECT_NAME. If a server belongs to several clusters, there is a
- member MBean for each cluster, and all these members have the same value for the ServerProxy attribute.
- There are several types of member MBeans. They correspond to the several cluster types. The
- LogicalClusterMember
- MBeans are used to represent LogicalCluster members.
- Mod_jk load balancing clusters. The members of such a cluster are workers defined in
-the mod_jk configuration file workers.properties. The workers correspond to JOnAS server instances
-having the web service based on Tomcat and a specific configuration (server.xml having a Connector
-XML element for AJP1.3 protocol defined, as well as the Engine element having the jvmRoute attribute
-set to the worker name).
- The ObjectNames corresponding to Mod_jk clusters and Mod_jk cluster members are: -
- domainName:type=JkCluster,name=clusterName --
- domainName:type=JkClusterMember,name=workerName,JkCluster=clusterName -- The workerName and clusterName are defined in the workers.properties configuration file. - -
Tomcat session replication clusters. The members are JOnAS-Tomcat cluster servers having
-a Cluster element defined in server.xml file. The management infrastructure detects
-Tomcat cluster members by looking for Tomcat Cluster MBeans in the managed server's MBean server.
- The ObjectNames corresponding to Tomcat session replication clusters and Tomcat cluster members are: -
- domainName:type=TomcatCluster,name=clusterName --
- domainName:type=TomcatClusterMember,name=serverName,TomcatCluster=clusterName -- The clusterName can be defined in the server.xml configuration file. - -
CMI clusters. The members are JOnAS cluster servers sharing the same CMI configuration
-for the JNDI replication and the EJB clustering.
- The ObjectNames corresponding to the CMI clusters and cluster members are: -
- domainName:type=CmiCluster,name=clusterName --
- domainName:type=CmiClusterMember,name=serverName,CmiCluster=clusterName -- The clusterName can be defined in the carol.properties configuration file and - represents a JavaGroups group name. - -
HA clusters. The members are JOnAS cluster servers sharing the same HA service configuration
-for the EJB replication.
- The ObjectNames corresponding to the HA clusters and cluster members are: -
- domainName:type=HaCluster,name=clusterName --
- domainName:type=HaClusterMember,name=serverName,HaCluster=clusterName -- The clusterName can be defined in the jonas.properties configuration file and - represents a JavaGroups group name. - -
The servers must adhere to these rules:
-Also note the following:
-Consider a scenario in which there are three JOnAS servers named jonas, j1 and j2. - Assume that they have discovery service configured with at least one of the servers playing the role of master. -
-- jonas start -
- jonas start -n j1 -Ddomain.name=jonas -
- jonas start -n j2 -Ddomain.name=jonas -
A default domain configuration is provided in $JONAS_ROOT/conf/domain.xml.
-This configuration corresponds to a domain named jonas managed by a master
-server also named jonas. The location tag defines a JMX remote
-connector server URL for this server.
-
Last modified at 2006-11-30, JOnAS 4.8
-
-
-This document provides an overview of the JOnAS platform. The content of -this document is the following:
-The SunTM J2EE -specification, together with its related specifications ( EJBTM, JMSTM,...), defines -an architecture and interfaces for developing and deploying distributed -Internet JavaTM server applications based on a multi-tier -architecture. This specification intends to facilitate and standardize the -development, deployment, and assembling of application components; such -components will be deployable on J2EE platforms. The resulting applications -are typically web-based, transactional, database-oriented, multi-user, -secured, scalable, and portable. More precisely, this specification describes -two kinds of information:
-Not only will an application component be independent of the platform and -operating system (since it is written in Java), it will also be independent -of the J2EE platform.
- -A typical J2EE application is composed of 1) presentation components, also -called "web components" (Servlets and JSPsTM), which define -the application Web interface, and 2) enterprise components, the "Enterprise -JavaBeans" (EJB), which define the application business logic and application -data. The J2EE server provides containers for hosting web and enterprise -components. The container provides the component life-cycle management and -interfaces the components with the services provided by the J2EE server. -There are two types of containers; the web container handles Servlet and JSP -components, while the EJB container handles the Enterprise JavaBeans -components. A J2EE server can also provide an environment for deploying Java -clients (accessing EJBs); it is called client container.
-
-
-JOnAS is an open source application server, developed within the ObjectWeb -consortium. ObjectWeb is an open -source initiative which can be compared to Apache or Linux, but in the area -of middleware. The aim of ObjectWeb is to develop and -promote open source middleware software.
- -ObjectWeb is an International Consortium hosted by INRIA, officially -founded in February 2002 by Bull, France Telecom, and INRIA. All software is -available with the LGPL license.
- -The technical objective of this consortium is to develop a distributed -component-based, middleware technology, in line with CORBA, Java, and W3C -standards. The intent is to apply the component model, as already used at the -application level in J2EE and in the CORBA Component Model, at the middleware -level itself. The functional coverage of ObjectWeb projects addresses naming, -trading, communication (events, messages), availability and safety -(transactions, persistence, replication, fault tolerance), load balancing, -and security. Some related topics are also addressed, such as robustness, -optimization, code quality, as well as benchmarks, tests, evaluations, -demonstrators, and development tools. More recently, the middleware -eco-system around JOnAS within ObjectWeb addresses Service Oriented -Architecture (SOA).
- -ObjectWeb already has a significant number of members: corporations, -universities, individual members (individual membership is free). ObjectWeb -members contribute to ObjectWeb orientations and participate in all ObjectWeb -working groups, meetings, workshops, and conferences. The community of -developers and users working with ObjectWeb components and platforms is -constantly growing.
- -JOnAS is a pure Java, open source, application server. Its high modularity -allows to it to be used as
-JOnAS is available for JDK 1.4 and JDK 5. It has been used on many -operating systems (Linux, AIX, Windows, Solaris, HP-UX, etc.), and with -different Databases (Oracle, PostgreSQL, MySQL, SQL server, Access, DB2, -Versant, Informix, Interbase, etc.).
- -JOnAS supports the deployment of applications conforming to J2EE 1.4 -specification. Its current integration of Tomcat or Jetty as a Web container -ensures conformity to Servlet 2.4 and JSP 2.0 specifications. The JOnAS -server relies on or implements the following Java APIs: EJBTM 2.1, -JTATM 1.0.1, JDBC 3.0, J2EE CATM 1.5, JMXTM -1.2, JNDITM 1.2.1, JMSTM 1.1, JavaMailTM -1.3, ServletTM 2.4, JSPTM 2.0, JAASTM 1.0, -JACCTM 1.0, Web Services 1.1, JAX-RPCTM 1.1, -SAAJTM 1.2, JAXRTM 1.0, J2EE Management 1.0, -JAFTM 1.0, JAXPTM 1.2 specifications. JOnAS is -architectured in terms of services.
- -JOnAS provides the following important advanced features:
-JOnAS benefits from transparent local RMI call optimization.
-Three critical J2EE aspects were implemented early on in the JOnAS -server:
-JOnAS is available for download with three different packagings:
-These packages also contain AXIS, thus providing pre-configured "Web -Services" support.
- -JOnAS is designed with services in mind. A service typically provides -system resources to containers. Most of the components of the JOnAS -application server are pre-defined JOnAS services. However, it is possible -and easy for an advanced JOnAS user to define a service and to integrate it -into JOnAS. Because J2EE applications do not necessarily need all services, -it is possible to define, at JOnAS server configuration time, the set of -services that are to be launched at server start.
- -The JOnAS architecture is illustrated in the following figure, showing WEB -and EJB containers relying on JOnAS services (this figure only misses the HA -service). Two thin clients are also shown in this figure, one of which is the -JOnAS administration console (called JonasAdmin).
-
-
-This service (also called "Registry") is used for launching the RMI -registry, the CosNaming, and/or the CMI registry, depending on the JOnAS -configuration (CAROL configuration, which specifies which communication -protocols are to be used). There are different registry launching modes: in -the same JVM or not, automatically if not already running. CAROL enables -multi-protocol runtime support and deployment, which avoids having to -redeploy components when changing the communication protocol.
- -This service provides the JNDI API to application components and to other -services in order to bind and lookup remote objects (e.g. EJB Homes) and -resource references (JDBC DataSource, Mail and JMS connection factories, -etc.).
- -This service is in charge of loading the EJB 2.1 components and their -containers. EJB containers consist of a set of Java classes that implement -the EJB specification and a set of interposition classes that interface the -EJB components with the services provided by the JOnAS application server. -Interposition classes are specific to each EJB component and are generated by -the deployment tool called GenIC; this tool is automatically called at -deployment time, if necessary.
- -Enterprise JavaBeans (EJB) are software components that implement the -business logic of an application (while the Servlets and JSPs implement the -presentation). There are three types of Enterprise JavaBeans:
-JOnAS configuration provides a means for specifying a set of ejb-jar files -to be loaded at server start. Ejb-jar files can also be deployed at server -runtime using the JOnAS administration tools.
- -For implementing Container-Managed Persistence of EJB 2.0 and EJB 2.1 -(CMP2), JOnAS relies on the ObjectWeb JORM (Java Object Repository Mapping) -and MEDOR (Middleware Enabling -Distributed Object Requests) frameworks. JORM supports complex mappings of -EJBs to database tables.
- -The JOnAS EJB 2.1 container provides many optimization mechanisms to -improve data access and scalability: pool of instances, caches, lock -policies...
- -JOnAS also implements the Timer Service features as specified in EJB -2.1.
- -This service is in charge of running a Servlet/JSP Engine in the JVM of -the JOnAS server and of loading web applications ("war" files) within this -engine. Currently, this service can be configured to use Tomcat or Jetty. Servlet/JSP engines are -integrated within JOnAS as "web containers," i.e. such containers provide the -web components with access to the system resources (of the application -server) and to EJB components, in a J2EE-compliant way.
- -JOnAS configuration provides a means for specifying that this service be -launched during JOnAS initialization. Additionally, JOnAS configuration -provides a means for specifying a set of war files to be loaded. War files -may also be deployed at server runtime using the JOnAS administration tools. -User management for Tomcat/Jetty and JOnAS has been unified. The -class-loading delegation policy (priority to the Webapp classloader or to the -parent classloader) can be configured. Tomcat management has been strongly -integrated within the JOnAS management console.
- -Servlet and JSPTM are technologies -for developing dynamic web pages. The Servlet approach allows the development -of Java classes (HTTP Servlets) that can be invoked through HTTP requests and -that generate HTML pages. Typically, Servlets access the information system -using Java APIs (as JDBC or the APIs of EJB components) in order to build the -content of the HTML page they will generate in response to the HTTP request. -The JSP technology is a complement of the Servlet technology. A JSP is an -HTML page containing Java code within particular XML-like tags; this Java -code is in charge of generating the dynamic content of the HTML page.
- -Servlets and JSPs are considered as J2EE application components, -responsible for the application presentation logic. Such application -components can access resources provided by the J2EE server (such as JDBC -datasources, JMS connection factories, EJBs, mail factories). For J2EE -components, the actual assignment of these resources is performed at -component deployment time and is specified in the deployment descriptor of -each component, since the component code uses logical resource names.
- -This service is used for deploying complete J2EE applications, i.e. -applications packaged in EAR files, which themselves contain ejb-jar files -and/or war files. This service handles the EAR files and delegates the -deployment of the war files to the WEB Container service and the ejb-jar -files to the EJB Container service. It handles creating the appropriate class -loaders, in order for the J2EE application to execute properly.
- -For deploying J2EE applications, JOnAS must be configured to launch the -EAR service and to specify the set of EAR files to be loaded. EAR files can -also be deployed at server runtime using the JOnAS administration tools.
- -This service encapsulate a Java Transaction Monitor called JOTM (a project from ObjectWeb). It is a -mandatory service which handles distributed transactions. It provides -transaction management for EJB components as defined in their deployment -descriptors. It handles two-phase commit protocol against any number of -Resource Managers (XA Resources). For J2EE, a transactional resource may be a -JDBC connection, a JMS session, or a J2EE CA Resource Adapter connection. The -transactional context is implicitly propagated with the distributed requests. -The Transaction Monitor can be distributed across one or more JOnAS servers; -thus a transaction may involve several components located on different JOnAS -servers. This service implements the JTA 1.0.1 specification, thus allowing -transactions from application components or from application clients to be -explicitly started and terminated. Starting transactions from application -components is only allowed from Web components, session beans, or -message-driven beans (only these two types of beans, which is called -"Bean-managed transaction demarcation").
- -One of the main advantages of the EJB support for transactions is its -declarative aspect, which means that transaction control is no longer -hard-coded in the server application, but is configured at deployment time. -This is known as "Container-managed transaction demarcation." With -"Container-managed transaction demarcation," the transactional -behaviour of an enterprise bean is defined at configuration time and is part -of the deployment descriptor of the bean. The EJB container is responsible -for providing the transaction demarcation for the enterprise beans according -to the value of transactional attributes associated with EJB methods, which -can be one of the following:
-NotSupported: If the method is called
- within a transaction, this transaction is suspended during the time of
- the method execution.Required: If the method is called within
- a transaction, the method is executed in the scope of this transaction,
- else, a new transaction is started for the execution of the method and
- committed before the method result is sent to the caller.RequiresNew: The method will always be
- executed within the scope of a new transaction. The new transaction is
- started for the execution of the method, and committed before the method
- result is sent to the caller. If the method is called within a
- transaction, this transaction is suspended before the new one is started,
- and resumed when the new transaction has completed.Mandatory: The method should always be
- called within the scope of a transaction, else the container will throw
- the TransactionRequired exception.Supports: The method is invoked within
- the caller transaction scope. If the caller does not have an associated
- transaction, the method is invoked without a
- transaction scope.
-Never: With this attribute the client is
- required to call the method without a transaction context, else the
- Container throws the java.rmi.RemoteException exception.This service is responsible for handling Datasource objects. A Datasource -is a standard JDBC administrative object for handling connections to a -database. The Database service creates and loads such datasources on the -JOnAS server. Datasources to be created and deployed can be specified at -JOnAS configuration time, or they can be created and deployed at server -runtime using the JOnAS administration tools. The Database service is also -responsible for connection pooling; it manages a pool of database connections -to be used by the application components, thus avoiding many physical -connection creations, which are time-consuming operations. The database -service can now be replaced by the JDBC Resource Adapter, to be deployed by -the J2EE CA Resource Service, which additionally provides JDBC -PreparedStatement pooling.
- -This service implements the authorization mechanisms for accessing J2EE -components, as specified in the J2EE specification.
-getCallerPrincipal() and isCallerInRole (String
- roleName). The role names used in the EJB code (in the
- isCallerInRole method) are, in fact, references to actual security roles,
- which makes the EJB code independent of the security configuration
- described in the deployment descriptor. The programmer makes these role
- references available to the bean deployer or application assembler by way
- of the security-role-ref elements included in the
- session or entity elements of the deployment
- descriptor.isUserInRole (String roleName) method.In JOnAS, the mapping between roles and user identification is done in the -user identification repository. This user identification repository can be -stored either in files, in a JNDI repository (such as LDAP), or in a -relational database. This is achieved through a JOnAS implementation of the -Realm for each Web container and through the JAAS login modules for Java -clients. These Realms use authentication resources provided by JOnAS, which -rely either on files, LDAP or JDBC. These realms are in charge of propagating -the security context to the EJB container during EJB calls. JAAS login -modules are provided for user authentication of Web Container and Java -clients. Certificate-based authentication is also available, with -CRLLoginModule login module for certificate revocation.
- -JOnAS also implements the Java Authorization Contract for Containers (JACC -1.0) specification, allowing authorizations to be managed as java security -permissions, and providing the ability to plug any security policy -provider.
- -Asynchronous EJB method invocation is possible on Message-driven Beans -components. A Message-driven Bean is an EJB component that can be considered -as a JMS (Java Message -Service) MessageListener, i.e. which processes JMS messages -asynchronously. It is associated with a JMS destination and its -onMessage method is activated on the reception of messages sent by a -client application to this destination. It is also possible for any EJB -component to use the JMS API within the scope of transactions managed by the -application server.
- -For supporting Message-driven Beans and JMS operations coded within -application components, the JOnAS application server relies on a JMS -implementation. JOnAS makes use of a third-party JMS implementation; -currently the JORAM open source -software is integrated and delivered with JOnAS, and other JMS provider -implementations can easily be integrated. JORAM provides several noteworthy -features: in particular, reliability (with a persistent mode), distribution -(transparently to the JMS client, it can run as several servers, thus -allowing load balancing), and the choice of TCP or SOAP as communication -protocol for transmitting messages.
- -The JMS service is in charge of launching (or establishing connection to) -the integrated JMS server, which may or may not run in the same JVM as JOnAS. -It also provides connection pooling and thread pooling (for Message-driven -Beans). Through this service, JOnAS provides facilities to create -JMS-administered objects such as the connection factories and the -destinations, either at server launching time or at runtime using the JOnAS -administration tools.
- -Note that the same function of JMS implementation integration may now be -achieved through a Resource Adapter, to be deployed by the J2EE CA Resource -Service. Such a Resource Adapter (J2EE CA 1.5) is provided for JORAM.
- -The J2EE Connector Architecture (J2EE CA) allows the connection of -different Enterprise Information Systems (EIS) to a J2EE application server. -It is based on the Resource Adapter (RA), an architecture component -comparable to a software driver, which connects the EIS, the application -server, and the enterprise application (J2EE components). The RA is generally -provided by an EIS vendor and provides a Java interface (the Common Client -Interface or CCI) to the J2EE components for accessing the EIS (this can also -be a specific Java interface). The RA also provides standard interfaces for -plugging into the application server, allowing them to collaborate to keep -all system-level mechanisms (transactions, security, and connection -management) transparent from the application components.
-
-
-The application performs "business logic" operations on the EIS data using -the RA client API (CCI), while transactions, connections (including pooling), -and security on the EIS are managed by the application server through the RA -(system contract).
- -The JOnAS Resource service is in charge of deploying J2EE CA-compliant -Resource Adapters (connectors), packaged as RAR files, on the JOnAS server. -RAR files can also be included in EAR files, in which case the connector will -be loaded by the application classloader. Once Resource Adapters are -deployed, a connection factory instance is available in the JNDI namespace to -be looked up by application components.
- -A J2EE CA 1.0 Resource Adapter for JDBC is available with JOnAS. It can -replace the current JOnAS database service for plugging JDBC drivers and -managing connection pools. It also provides JDBC PreparedStatement -pooling.
- -A J2EE CA 1.5 Resource Adapter for JMS is available with JOnAS. It can -replace the current JOnAS Messaging service for plugging JORAM.
- -The Management service is needed to administrate a JOnAS server from the -JOnAS administration console. Each server running this service is visible -from the administration console. This service is based on JMX. Standard -MBeans are defined within the JOnAS application server; they expose the -management methods of the instrumented JOnAS server objects such as services, -containers, the server itself. These MBeans implements the management model -as specified in the J2EE Management Specification. The Management service -runs a JMX server (if not available within the JDK, as is the case with JDK -5). The MBeans of the JOnAS server are registered within this JMX server. The -JOnAS administration console is a Struts-based Web application (servlet/JSP) -that accesses the JMX server to present the managed features within the -administration console. Thus, through a simple Web browser, it is possible to -manage one or several JOnAS application servers. The administration console -provides a means for configuring all JOnAS services (and making the -configuration persistent), for deploying any type of application (EJB-JAR, -WAR, EAR) and any type of resource (DataSources, JMS and Mail connection -factories, J2EE CA connectors), all without the need to stop or restart the -server. The administration console displays information for monitoring the -servers and applications, such as used memory, used threads, number of EJB -instances, the state of pools, which component currently uses which -resources, etc.. When Tomcat is used as Web Container, the Tomcat Management -is integrated within the JOnAS console. The concept of domain allows a set of -servers to be managed from a single management console, clusters have been -introduced within the console, allowing, for example, an application to be -deployed on a predefined subset of JOnAS instances. The cluster management -allows remote control and monitoring of cluster nodes; EJB and HTTP clusters -resulting from HA and load balancing configurations are automatically -detected and displayed in the console. A Management EJB (MEJB) is also -delivered, providing access to the management features, as specified in the -J2EE Management Specification. This MEJB is also accessible through Web -Services. JASMINe, a new ObjectWeb -project dedicated to cluster deployment and monitoring has been created.
- -A J2EE application component can send e-mail messages using JavaMailTM. The -Mail service of the JOnAS application server provides the necessary resources -to such application components. The Mail service creates mail factories and -registers these resources in the JNDI namespace in the same way that the -database service or the JMS service creates Datasources or -ConnectionFactories and registers these objects in the JNDI namespace. There -are two types of mail factories: javax.mail.Session and -javax.mail.internet.MimePartDataSource.
- -This service is implemented on top of AXIS and is used for the deployment -of Web Services.
- -This service is used for implementing Stateful Session Beans replication, -when configuring high availibility at the EJB/RMI level within a clustered -environment.
- -Once JOnAS has been installed in a directory referenced by the JONAS_ROOT -environment variable, it is possible to configure servers and to deploy -applications into several execution environments. This is achieved using the -JONAS_BASE environment variable. JONAS_ROOT and JONAS_BASE can be compared to -the CATALINA_HOME and CATALINA_BASE variables of Tomcat. While JONAS_ROOT is -dedicated to JOnAS installation, JONAS_BASE is used to specify a particular -JOnAS instance configuration. JONAS_BASE designates a directory containing a -specific JOnAS configuration, and it identifies subdirectories containing the -EJB-JAR, WAR, EAR, and RAR files that can be loaded in this application -environment. There is an ANT target in the JOnAS build.xml file for creating -a new JONAS_BASE directory structure. Thus, from one JOnAS installation, it -is possible to switch from one application environment to another by just -changing the value of the JONAS_BASE variable. There are two ways to -configure a JOnAS application server and load applications: either using the -administration console or by editing the configuration files. There are also -"autoload" directories for each type of application and resource (EJB-JAR, -WAR, EAR, RAR) that allow the JOnAS server to automatically load the -applications located in these directories when starting.
- -A tool named "newjc" is provided to deploy and configure a set of JOnAS -servers within a cluster.
- -JOnAS provides several facilities for deployment:
-Fractal Deployment Framework (FDF) is a tool for deploying and configuring -the JOnAS software on a distributed environment.
- -There are many plugins and tools that facilitate the development of J2EE -applications to be deployed on JOnAS. IDE plugins for Eclipse (JOPE, Lomboz, and, of course, WTP) and JBuilder (Kelly) provide the -means to develop, deploy, and debug J2EE components on JOnAS. The Xdoclet code-generation engine can -generate EJB interfaces and deployment descriptors (standard and JOnAS -specific ones), taking as input the EJB implementation class containing -specific JavaDoc tags. The JOnAS NewBean tool generates templates of -interfaces, implementation class, and deployment descriptors for any kind of -EJB. Many development tools may work with JOnAS; refer to the JOnAS tools page for -more details.
- -In addition, JOnAS is delivered with complete J2EE examples, providing a -build.xml ANT file with all the necessary targets for compiling, deploying, -and installing J2EE applications.
- -Clustering for an application server generally makes use of three -features: Load Balancing (LB), High Availability (HA) and Failover. Such -mechanisms can be provided at the Web container level by dispatching requests -to several Servlet/JSP engine instances, at the EJB container level by -dispatching EJB requests to several EJB container instances, and at the -database level by using several databases. A replicated JNDI naming is also -necessary.
- -JOnAS provides Load Balancing, HA, and Failover at the WEB container level -using the Apache Tomcat mod_jk plugin and an HTTP in memory -session-replication mechanism based on JGroups. The plugin dispatches HTTP -requests from the Apache web server to Tomcat instances running as JOnAS web -containers. Server fluctuations are automatically taken into account. This -plugin supports round-robin and weighted round-robin load-balancing -algorithms, with a sticky session option.
- -Load balancing and HA are provided at the EJB container level in JOnAS. -Operations invoked on EJB Home interfaces (EJB creation and retrieval) and -invocations of business methods on stateless session beans are dispatched on -the nodes of the cluster. The mechanism is based on a "clustered-aware" -replicated JNDI registry using a Clustered remote Method Invocation protocol -(CMI). The stubs contain the knowledge of the cluster and implement the -load-balancing policy, which may be round-robin and weighted round-robin; -these stubs are dynamically updated according to cluster topology changes -(dynamic cluster). This load-balancing policy may be easily customized. -Failover at the EJB level is provided by implementing a stateful session bean -state replication mechanism that ensures the transaction and global -consistency.
- -Load balancing and HA may also be provided at the JMS level, thanks to the -JORAM HA capabilities.
- -The JOnAS clustering architecture is illustrated in the following -figure.
-
-
-Apache is used as the front-end HTTP server; Tomcat is used as the JOnAS -web container. The JOnAS servers share the same database. The mod_jk plug-in -provides Load Balancing / High Availability at the Servlet/JSP level. -Failover is provided through the in-memory, session-replication mechanism. -Load Balancing / High Availability is provided at the EJB level through the -CMI protocol associated with the replicated, clustered-aware JNDI registry. -Tomcat may or may not run in the same JVM as the EJB container. JOnAS -provides some documentation for configuring such an architecture.
- -The use of the C-JDBC ObjectWeb -project offers load balancing and high availability at the database level. -The use of C-JDBC is transparent to the application (in our case to JOnAS), -since it is viewed as a standard JDBC driver. However, this "driver" -implements the cluster mechanisms (reads are load-balanced and writes are -broadcasted). The database is distributed and replicated among several nodes, -and C-JDBC load balances the queries between these nodes. An evaluation of -C-JDBC using the TPC-W benchmark on a 6-node cluster has shown performance -scaling linearly up to six nodes.
- -In addition to clustering solutions, JOnAS provides many mechanisms, -intrinsic to the JOnAS server, for being highly scalable and efficient. This -includes the following:
-As an open source implementation of an application server, JOnAS is -constantly evolving to satisfy user requirements and to follow the related -standards. The main JOnAS evolutions currently planned are the following:
-Sun, Java, and all -Java-based trademarks are trademarks or registered trademarks of Sun -Microsystems, Inc. in the U.S. and other countries.
- - diff --git a/jonas_doc/olddoc/JOnASWebServices.html b/jonas_doc/olddoc/JOnASWebServices.html deleted file mode 100644 index 7f8707b2e86071133e89c6190444beafedb49047..0000000000000000000000000000000000000000 --- a/jonas_doc/olddoc/JOnASWebServices.html +++ /dev/null @@ -1,814 +0,0 @@ - - - - -Strictly speaking, a Web Service is a well-defined, modular, encapsulated -function used for loosely coupled integration between applications' or -systems' components. It is based on standard technologies, such as XML, SOAP, -and UDDI.
- -Web Services are generally exposed and discovered through a standard -registry service. With these standards, Web Services consumers (whether they -be users or other applications) can access a broad range of information -- -personal financial data, news, weather, and enterprise documents -- through -applications that reside on servers throughout the network.
- -Web Services use a WSDL Definition (refer to www.w3.org/TR/WSDL) as a contract -between client and server (also called endpoint). WSDL defines the types to -serialize through the network (described with XMLSchema), the messages to -send and receive (composition, parameters), the portTypes (abstract view of a -Port), the bindings (concrete description of PortType: SOAP, GET, POST, ...), -the services (set of Ports), and the Port (the port is associated with a -unique endpoint URL that defines the location of the Web Service).
- -A Web Service for J2EE is a component with some methods exposed and -accessible by HTTP (through servlet(s)). Web Services can be implemented as -Stateless Session Beans or as JAXRPC classes (a simple Java class, no -inheritance needed).
- -
The servlet is used to respond to a client request and dispatch the call -to the designated instance of servant (the SSB or JAXRPC class exposed as Web -Service). It handles the deserialization of incoming SOAP messages to -transform SOAP XML into a Java Object, perform the call, and serialize the -call result (or the thrown exception) into SOAP XML before sending the -response message to the client.
-In this Descriptor, the developer describes the components that will be -exposed as Web Services' endpoints; these are called the port-component(s). A -set of port-components defines a webservice-description, and a -webservice-description uses a WSDL Definition file for a complete description -of the Web Services' endpoints.
- -Each port-component is linked to the J2EE component that will respond to -the request (service-impl-bean with a servlet-link or ejb-link child element) -and to a WSDL port (wsdl-port defining the port's QName). A list of JAX-RPC -Handlers is provided for each port-component. The optional -service-endpoint-interface defines the methods of the J2EE components that -will be exposed (no inheritance needed).
- -A JAX-RPC Handler is a class used to read and/or modify the SOAP Message -before transmission and/or after reception (refer to the JAX-RPC v1.1 spec. -chap#12 "SOAP Message Handlers").The Session Handler is a simple example that -will read/write SOAP session information in the SOAP Headers. Handlers are -identified with a unique name (within the application unit), are initialized -with the init-param(s), and work on processing a list of SOAP Headers defined -with soap-headers child elements. The Handler is run as the SOAP actor(s) -defined in the list of soap-roles.
- -A webservice-description defines a set of port-components, a WSDL
-Definition (describing the Web Service) and a mapping file (WSDL-2-Java
-bindings). The wsdl-file element and the jaxrpc-mapping-file element must
-specify a path to a file contained in the module unit (i.e., the war/jar
-file). Note that a URL cannot be set here. The specification also requires
-that the WSDLs be placed in a wsdl subdirectory (i.e., WEB-INF/wsdl or
-META-INF/wsdl); there is no such requirement for the jaxrpc-mapping-file. All
-the ports defined in the WSDL must be linked to a port-component. This is
-essential because the WSDL is a contract between the endpoint and a client
-(if the client uses a port not implemented/linked with a component, the
-client call will systematically fail).
-
As for all other Deployment Descriptors, a standard
-XML Schema is used to constrain the XML.
-
<?xml version="1.0"?> <!-- Unique name of
- the port-component --><!-- Should not contain spaces !!!
- -->-
- <port-component-name>WebappPortComp1</port-component-name>http://wsendpoint.servlets.ws.objectweb.org"> <!-- The endpoint
- interface defining methods exposed -->-
- <service-endpoint-interface> <!-- Link to the J2EE
- component (servlet/EJB) -->-
- <service-impl-bean> <!-- can
- be ejb-link if SSB is used (only in EjbJar!)
- -->-
- <servlet-link>WSEndpoint</servlet-link> <!-- The list of
- optional JAX-RPC Handlers -->- <handler> <!-- A
- list of init-param for Handler configuration -->-
- <init-param> |
-
jonas-webservices.xml file is an optional deployment descriptor. This descriptor
-is used by WsGen to set some specifics for the generated webapp that is in charge of
-the SOAP request dispatching. Its role is to allow for the specifications of the
-webapp's name, context root, security settings and endpoint URL customization.jonas:jonas-webservices/jonas:war: specify the filename of the webapp
-frontend generated for this EjbJarjonas:jonas-webservices/jonas:context-root: specify the context root of the webapp
-frontend generated for this EjbJar
-xmlsn:j2ee="http://java.sun.com/xml/j2ee"), and the namespace
-for all elements within these tags (that is, the 'j2ee'
-in the example below) must be specified.
-
- |
-
<service-ref>(Optional) A Web services
- description that can be used -->(Optional) The WebService
- reference name -->(Optional) An icon for this
- WebService. --> The logical name for the reference
- that is used in the client source --> Defines the class name of the
- JAX-RPC Service interface that--> (Optional) Contains the location
- (relative to the root of (Optional) A file specifying the
- correlation of the WSDL definition --> (Optional) Declares the specific
- WSDL service element that is being -->http://beans.ws.objectweb.org">Declares a client dependency on
- the container for resolving a Service -->- org.objectweb.ws.beans.ssbendpoint.MyService- - </service-endpoint-interface></port-component-link>- </port-component-ref>Must be unique
- within the module. -->http://ws.objectweb.org">SOAP actor
- definitions that the Handler will play -->port-name elements that defines the WSDL
- port-name that
- --> |
-
- <jonas-service-ref> <!-- Define the service-ref
- contained in the component
- <service-ref-name>services/myService</service-ref-name> <!-- Define the physical
- name of the resource. -->
- <jndi-name>webservice_1</jndi-name> |
-
WsGen is a new JOnAS tool that works in the same way as GenIC. It takes -archive files (EJB-JAR, WAR, JAR client, EAR) and generates all the necessay -components related to web services:
-For example, to provide an EJB-exposing method as a web service, a -developer creates a webservices.xml file packaged in EjbJar's -META-INF directory. WsGen automatically creates a configured webapp (using an -Axis servlet) and wraps it (ejbjar + webapp) in an EAR file.
- -With a JaxRpc class, WsGen adds a servlet (an Axis servlet) inside the -existing web deployment descriptor and generates an Axis-specific -configuration file.
- -When using service-ref (from ejbjars, web applications, or clients), WsGen -automatically generates a Stub from WSDL (if a generated service interface -name is provided).
- -WsGen is used typically from an ant build file. Simply add this taskdef -under the ejbjar taskdef:
-<taskdef name="wsgen" classname="org.objectweb.jonas.ant.WsGenTask"
- classpath="${jonas.root}/lib/common/ow_jonas_ant.jar" />
-<wsgen srcdir="${temp.dir}"
- destdir="${dist.dir}"
- verbose="false"
- debug="false">
- <include name="webapps/wswarsample.war"/>
-</wsgen>
-
-See the $JONAS_ROOT/examples/webservices samples for complete -build scripts.
- -Note that the ejbjar/webapp/client archive must include WSDL, -jax-rpc-mappings used in service-ref, or webservices.xml. When these -files are used from a service-ref, they are added into the generic ejb-jar -with the ejbjar ant task of JOnAS; you must ensure that they have been placed -inside the srcdir given to the ejbjar task (otherwise, the ejbjar task cannot -find them and will produce an error).
- -This task is a directory-based -task and, as such, forms an implicit Fileset. This -defines which files, relative to the srcdir, will be processed. The -wsgen task supports all the attributes of Fileset to refine the set of files -to be included in the implicit fileset.
- -| Attribute | -Description | -Required | -
|---|---|---|
| srcdir | -Directory where file archive (EjbJar, War, Client, Ear) is - located | -Yes | -
| destdir | -Directory where generated files will be placed | -No | -
| verbose | -Verbose mode (Defaults to false) | -No | -
| debug | -Debug mode (Defaults to false) | -No | -
| javacopts | -List of options given to the java compiler | -No | -
| jonasroot | -Directory where JOnAS is installed | -No | -
| jonasbase | -Directory where JOnAS configuration is stored | -No | -
Wsgen is also usable from the command line with WsGen script (available on -*nix and Windows).
- -The content of this guide is the following:
-This chapter is intended for advanced JOnAS users who are interested in -understanding management facilities that JOnAS provides, and possibly -extending these facilities for their application needs.
- -JOnAS management facilities are based on Management Beans (MBeans) -compliant to JMX -Specification. Moreover, JOnAS implements JSR 77 specification, which -defines the management model for J2EE platforms.
- -MBeans provide access to management functions such as configuration, -deployment/undeployment, monitoring of resources and application modules.
- -MBeans are created not only by the different JOnAS services, but also by the -components integrated in JOnAS (Web server Tomcat or Jetty, JORAM MOM, etc.). -They are registered in the current MBean Server, which is started by each -JOnAS server instance. Remote access to the MBean Server is facilitated by -JMX remote connectors compliant to the JSR 160 specification. See more -information about connectors here.
- -JonasAdmin application implements the management functions listed above -using the different MBeans registered in the MBeanServer of the JOnAS -instance currently being managed. This is usually the server on which -JonasAdmin is deployed, but it may be another server running in the same -management domain.
- -JonasAdmin also presents, in a structured way, all the registered MBeans, -their attributes and operations. In the future, JonasAdmin will probably be -extended to allow setting attributes and invoking operations.
- -In order to invoke a management operation on a MBean, the caller must -access to the MBean server.
- -When the caller is located in the same JVM as the MBean Server, it can use
-javax.management.MBeanServerFactory class to obtain a reference
-to the MBean Server:
List mbeanServers = MBeanServerFactory.findMBeanServer(null);
- if (mbeanServers != null && mbeanServers.size() > 0) {
- return (MBeanServer) mbeanServers.get(0);
- }
-
-
-
-
-When the caller is remote, it can use a JMX remote connector to establish
-a connection with the MBean Server and obtain a
-javax.management.MBeanServerConnection object.
Suppose that the connector server has the following address:
-service:jmx:jrmp://host/jndi/jrmp://host:1099/jrmpconnector_jonas,
-which is the default for a JOnAS server called jonas.
JMXServiceURL connURL = new JMXServiceURL("service:jmx:jrmp://host/jndi/jrmp://host:1099/jrmpconnector_jonas");
- JMXConnector connector = JMXConnectorFactory.newJMXConnector(connURL, null);
- connector.connect(null);
- MBeanServerConnection conn = connector.getMBeanServerConnection();
- return conn;
-
-
-
-
-A remote caller can also use the MEJB provided by the JOnAS distribution.
-A Management EJB implementation, compliant to the JSR 77, is packed in the
-mejb.ear installed in the
-JONAS_ROOT/ejbjars/autoload directory. Thus, the MEJB is
-automatically deployed at JOnAS start-up. Its Home is registered
-in JNDI under the name ejb/mgmt/MEJB. JOnAS distribution also
-contains an example using the MEJB in a J2EE application, the
-j2eemanagement sample.
-A remote caller can use the Management Web Service endpoint packaged
-as a part of the mejb.ear installed in the
-JONAS_ROOT/ejbjars/autoload directory. Thus, the management
-endpoint is automatically deployed at JOnAS start-up. Check
- http://<hostname>:<port>/mejb/ManagementEndpoint/ManagementEndpoint?wsdl
- for the WSDL file on a running JOnAS instance. The endpoint allows light-weight
-clients to query JOnAS MBeans from virtually any platform by leveraging the
-platform-independant nature of Web Services.
-
Application MBeans can be created and registered in the MBean server by
-calling registerMBean method on the MBeanServer
-object or createMBean method on the
-MBeanServerConnection object. Also, MBeans can be loaded using
-the m-let service, a dynamic loading mechanism provided by the JMX
-implementation. This mechanism allows loading MBeans from a remote URL. The
-information on the MBeans to load is provided in a m-let text file. Refer to
-JMX implementation documentation for details concerning this file. In addition,
-the howto document
-JOnAS and JMX, registering and manipulating MBeans
-illustrates the use of this m-let mechanism. In order
-to make an m-let text file accessible to JOnAS applications, it can be installed
-in the JONAS_ROOT/conf directory.
The target audience for this guide is the Client component provider, i.e. -the person in charge of developing the Client components on the client side. -It describes how the Client component provider should build the deployment -descriptors of its Client components and how the client components should be -packaged.
- -The content of this guide is the following:
-The J2EE client application can be
-All the files required to launch the client container are in the
-JONAS_ROOT/lib/client.jar file. This jar includes a manifest
-file with the name of the class to launch. To launch the client container,
-simply type:
java -jar $JONAS_ROOT/lib/client.jar -?. This will launch the
-client container and display usage information about this client
-container.
To launch the client container on a remote computer, copy the client.jar
-and invoke the client container by typing java -jar
-path_to_your/client.jar.
The client that must be launched by the client container is given as an
-argument of the client container.
-example : java -jar client.jar myApplication.ear
-or java -jar client.jar myClient.jar.
Defining the JNDI access and the protocol to use is an important part of
-configuration.
-The JOnAS server, as well as the ClientContainer, uses the values specified
-in the carol.properties file.
-This file can be used at different levels.
-The carol.properties is searched with the following priority
-(high to low):
carol.properties specified by the
- -carolFile argument to the client containercarol.properties packaged into the client application
- (the jar client)carol.properties contained in the
- JONAS_ROOT/lib/client.jar.A convenient way is to update the carol.properties of a
-client.jar with a customized carol.properties
-file. That is, use the jar -uf client.jar carol.properties
-command.
The client container client.jar includes a
-traceclient.properties file. This is the same file as the one in
-JONAS_ROOT/conf directory.
-A different configuration file can be used for the traces by specifying the
-parameter -traceFile when invoking the client container.
-The file in the client.jar can be replaced with the jar
--uf client.jar traceclient.properties command.
Some jars/classes can be added to the client container. For example if a class requires some extra libraries/classes,
-the option -cp path/to/classes can be used.
The classloader of the client container will use the libraries/classes provided by the -cp flag.
-
An ear can contain many java clients, which are described in the
-application.xml file inside the
-<module><java> elements.
-To invoke the client container with an ear, such as java -jar
-client.jar my.ear, specify the java client to use if there are many
-clients. Otherwise, it will take the first client.
-To specify the jar client to use from an ear, use the argument
--jarClient and supply the name of the client to use.
-The earsample example in the JOnAS examples has two java clients
-in its ear.
By default, the client container will use the system property
-java.io.tmpdir.
-To use another temporary directory, specify the path by giving the argument
--tmpDirto the client
-container.
By default, the client container will apply WsGen (generation of web services artifacts) on all given archives.
-To disable that feature (because WsGen has already been applied on the application, or because
-the client contains no web services), add the -nowsgen option to the client container.
The earsample and jaasclient examples of the
-JOnAS examples are packaged for use by the client container.
-The first example demonstrates the client inside an ear. The second example
-demonstrates the use of a standalone client.
The Client component programmer is responsible for providing the -deployment descriptor associated with the developed client components.
- -The client component provider's responsibilities and the Application
-Assembler's responsibilities are to provide an XML deployment descriptor that
-conforms to the deployment descriptor's XML DTD as defined in the Java
-TM Application Client Specification Version 1.4.(Refer to
-$JONAS_ROOT/xml/application-client_1_4.xsd or
-http://java.sun.com/xml/ns/j2ee/application-client_1_4.xsd).
To customize the Client components, information not defined in the
-standard XML deployment descriptor may be needed. Such information might
-include, for example, the mapping of the name of referenced resources to its
-JNDI name. This information can be specified during the deployment phase
-within another XML deployment descriptor that is specific to JOnAS. The
-JOnAS-specific deployment descriptor's XML schema is located in
-$JONAS_ROOT/xml/jonas-client_X_Y.xsd. The file name of the
-JOnAS-specific XML deployment descriptor must be
-'jonas-client.xml'.
JOnAS interprets the <!DOCTYPE> tag at the parsing of the deployment
-descriptor XML files.
-The parser first tries to get the specified DTD via the classpath, then it
-uses the specified URL (or path).
The parser gets the specified schema via the classpath (schemas are packaged -in the $JONAS_ROOT/lib/common/ow_jonas.jar file).
- -The standard deployment descriptor (application-client.xml) should contain -structural information that includes the following:
-The JOnAS-specific deployment descriptor (jonas-client.xml) may contain -information that includes the following::
-<?xml version="1.0" encoding="UTF-8"?> - -<application-client xmlns="http://java.sun.com/xml/ns/j2ee" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee - http://java.sun.com/xml/ns/j2ee/application-client_1_4.xsd" - version="1.4"> - - <display-name>Client of the earsample</display-name> - <description>client of the earsample</description> - - <env-entry> - <env-entry-name>envEntryString</env-entry-name> - <env-entry-type>java.lang.String</env-entry-type> - <env-entry-value>Test of envEntry of application-client.xml file</env-entry-value> - </env-entry> - - - <ejb-ref> - <ejb-ref-name>ejb/Op</ejb-ref-name> - <ejb-ref-type>Session</ejb-ref-type> - <home>org.objectweb.earsample.beans.secusb.OpHome</home> - <remote>org.objectweb.earsample.beans.secusb.Op</remote> - <ejb-link>secusb.jar#EarOp</ejb-link> - </ejb-ref> - - <resource-ref> - <res-ref-name>url/jonas</res-ref-name> - <res-type>java.net.URL</res-type> - <res-auth>Container</res-auth> - </resource-ref> - - <callback-handler>org.objectweb.jonas.security.auth.callback.LoginCallbackHandler - </callback-handler> - -</application-client>-
<?xml version="1.0" encoding="UTF-8"?> -<jonas-client xmlns="http://www.objectweb.org/jonas/ns" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://www.objectweb.org/jonas/ns - http://www.objectweb.org/jonas/ns/jonas-client_4_0.xsd"> - - <jonas-resource> - <res-ref-name>url/jonas</res-ref-name> - <jndi-name>http://jonas.objectweb.org</jndi-name> - </jonas-resource> - - <jonas-security> - <jaasfile>jaas.config</jaasfile> - <jaasentry>earsample</jaasentry> - <username>jonas</username> - <password>jonas</password> - </jonas-security> - -</jonas-client> --
Although some characters, such as ">", are legal, it is good practice -to replace them with XML entity references.
- -The following is a list of the predefined entity references for XML:
- -| < | -< | -less than | -
| > | -> | -greater than | -
| & | -& | -ampersand | -
| ' | -' | -apostrophe | -
| " | -" | -quotation mark | -
Client components are packaged for deployment in a standard Java -programming language Archive file called a jar file (Java ARchive). -The document root contains a subdirectory called META-INF, which -contains the following files and directories:
-The manifest of this client jar must contain the name of the class to
-launch (containing the main method). This is defined by the value of the
-Main-Class attribute of the manifest file.
-For a standalone client (not bundled in an Ear), all the Ejb classes (except
-the skeleton) on which lookups will be performed must be included.
Two examples of building a java client are provided.
-
build.xml of the
- earsample example with a java client inside the ear.build.xml of the
- jaasclient example with a java standalone client which
- performs a lookup on an EJB.The content of this guide is the following:
-This chapter is provided for advanced JOnAS users concerned with EAI -(Enterprise Application Integration) and using the J2EE Connector -Architecture principles (refer to the Appendix for an introduction to the connectors). -The target audience for this guide is the Resource Adapter deployer and -programmer. It describes the JOnAS specific deployment file -(jonas-ra.xml) and the sample code to access deployed RARs.
- -Resource Adapters are packaged for deployment in a standard Java -programming language Archive file called a rar file (Resource -ARchive), which is described in the J2EE Connector Architecture -specification.
- -The standard method for creating the jonas-ra.xml file is to use -the RAConfig tool. For a complete description refer to RAConfig.
- -The jonas-ra.xml contains JOnAS specific information describing -deployment information, logging, pooling, jdbc connections, and RAR config -property values.
-The following portion of a jonas-ra.xml file shows the linking to -a base RAR file named BaseRar. All properties from the base RAR will be -inherited and any values given in this jonas-ra.xml will override -the other values.
-<jonas-resource> - <jndiname>rar1</jndiname> - <rarlink>BaseRar</rarlink> - <native-lib>nativelib</native-lib> - <log-enabled>false</log-enabled> - <log-topic>com.xxx.rar1</log-topic> - <jonas-config-property> - <jonas-config-property-name>ip</jonas-config-property-name> - <jonas-config-property-value>www.xxx.com</jonas-config-property-value> - </jonas-config-property> - . - . - </jonas-resource>- -
The following portion of a jonas-ra.xml file shows the -configuration of a jdbc rar file.
-<jonas-resource> - <jndiname>jdbc1</jndiname> - <rarlink></rarlink> - <native-lib>nativelib</native-lib> - <log-enabled>false</log-enabled> - <log-topic>com.xxx.jdbc1</log-topic> - <pool-params> - <pool-init>0</pool-init> - <pool-min>0</pool-min> - <pool-max>100</pool-max> - <pool-max-age>0</pool-max-age> - <pstmt-max>20</pstmt-max> - </pool-params> - <jdbc-conn-params> - <jdbc_check-level>2</jdbc_check-level> - <jdbc-test-statement>select 1</jdbc-test-statement> - </jdbc-conn-params> - <jonas-config-property> - <jonas-config-property-name>url</jonas-config-property-name> - <jonas-config-property-value>jdbc:oracle:thin:@test:1521:DB1</jonas-config-property-value> - </jonas-config-property> - . - . - </jonas-resource>- -
Resource Adapters are packaged for deployment in a standard Java -programming language Archive file called an RAR file (Resource -Adapter ARchive). This file can contain the following:
-$JONAS_ROOT/xml/connector_1_5.xsd or
- http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd.
- This deployment descriptor must be stored with the name META-INF/ra.xml in
- the RAR file.Before deploying an RAR file, the JOnAS-specific XML must be configured
-and added. Refer to the RAConfig
-section for information.
Accessing Resource Adapter involves the following steps:
-<resource-ref> - <res-ref-name>eis/MyEIS</res-ref-name> - <res-type>javax.resource.cci.ConnectionFactory</res-type> - <res-auth>Container</res-auth> - </resource-ref> -- The mapping to the actual JNDI name of the connection factory - (here
adapt_1) is done in the JOnAS-specific deployment
- descriptor with the following element:
- <jonas-resource> - <res-ref-name>eis/MyEIS</res-ref-name> - <jndi-name>adapt_1</jndi-name> - </jonas-resource>-
This means that the bean programmer will have access to a - connection factory instance using the JNDI interface via the - java:comp/env/eis/MyEIS name:
- // obtain the initial JNDI naming context
- Context inictx = new InitialContext();
-
- // perform JNDI lookup to obtain the connection factory
- javax.resource.cci.ConnectionFactory cxf =
- (javax.resource.cci.ConnectionFactory)
- inictx .lookup("java:comp/env/eis/MyEIS");
- The bean programmer can then get a connection by calling the method
- getConnection on the connection factory.
- javax.resource.cci.Connection cx = cxf.getConnection(); -- The returned connection instance represents an application-level handle - to a physical connection for accessing the underlying EIS.
close method on the Connection interface:
- cx.close(); --
Build a JOnAS-specific resource adapter configuration
- file that will be included in the resource adapter.
- This jonas-ra XML file is used to configure the resource adapter in
- the operational environment and reflects the values of all
- properties declared in the deployment descriptor for the resource
- adapter, plus additional JOnAS-specific configuration properties.
- JOnAS provides a deployment tool RAConfig that is
- capable of building this XML file from an RA deployment descriptor
- inside an RAR file. Example:
RAConfig -path . -j adap_1 ra -- These properties may be specific for each resource adapter and its - underlying EIS. They are used to configure the resource adapter via - its
managedConnectionFactory class. It is mandatory
- that this class provide getter and setter method for each of its
- supported properties (as it is required in the Connector
- Architecture specification).
- After configuring the jonas-ra.xml file created above, it can be - added to the resource adapter by executing the following:
-RAConfig -u jonas-ra.xml ra -- This will add the xml file to the ra.rar file, which is now ready - for deployment.
jonas.properties file:
- resource is included in the
- jonas.services property.jonas.service.resource.resources property. If the
- '.rar' suffix is not used on the property, it will be used when
- trying to allocate the specified Resource Adapter.
- jonas.service.resource.resources MyEIS.rar, MyEIS1 --
jonas.service.resource.autoload in
- jonas.properties is configured differently.jonas admin -a xxx.rar"
- command.These generic JDBC resource adapters are supplied by JOnAS and are a
-replacement for the DBM service. Refer to Configuring JDBC Resource
-Adapters for a complete description and usage guide.
The Java Connector Architecture allows the connection of different -Enterprise Information Systems (EIS) to an application server such as JOnAS. -It defines a way for enterprise applications (based on EJB, servlet, JSP or -J2EE clients) to communicate with existing EIS. This requires the use of a -third party software component called "Resource Adapter" for each type of -EIS, which should be previously deployed on the application server. The -Resource Adapter is an architecture component comparable to a software -driver, which connects the EIS, the application server, and the enterprise -application (J2EE components in the case of JOnAS as application server). The -RA provides an interface (the Common Client Interface or CCI) to the -enterprise application (J2EE components) for accessing the EIS. The RA also -provides standard interfaces for plugging into the application server, so -that they can collaborate to keep all system-level mechanisms (transactions, -security, and connection management) transparent from the application -components.
-
-
-The resource adapter plugs into JOnAS and provides connectivity between -the EIS, JOnAS, and the application. The application performs "business -logic" operations on the EIS data using the RA client API (CCI), while -transactions, connections (including pooling), and security on the EIS is -managed by JOnAS through the RA (system contract).
- - diff --git a/jonas_doc/olddoc/PG_Deployment.html b/jonas_doc/olddoc/PG_Deployment.html deleted file mode 100644 index 5653807ccdc1e6ac0b9ccbeaaa29390c2e2734c1..0000000000000000000000000000000000000000 --- a/jonas_doc/olddoc/PG_Deployment.html +++ /dev/null @@ -1,329 +0,0 @@ - - - - - - -The target audience for this guide is the Enterprise Bean provider, i.e. -the person in charge of developing the software components on the server -side. It describes how the bean provider should build the deployment -descriptors of its components.
- -The content of this guide is the following:
-The bean programmer is responsible for providing the deployment descriptor
-associated with the developed Enterprise Beans. The Bean Provider's
-responsibilities and the Application Assembler's responsibilities is to
-provide an XML deployment descriptor that conforms to the deployment
-descriptor's XML schema as defined in the EBJ specification version 2.1. (Refer
-to $JONAS_ROOT/xml/ejb-jar_2_1.xsd or
-http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd).
To deploy Enterprise JavaBeans on the EJB server, information not defined
-in the standard XML deployment descriptor may be needed. For example, this
-information may include the mapping of the bean to the underlying database
-for an entity bean with container-managed persistence. This information is
-specified during the deployment step in another XML deployment descriptor
-that is specific to JOnAS. The JOnAS-specific deployment descriptor's XML schema
-is located in $JONAS_ROOT/xml/jonas-ejb-jar_X_Y.xsd. The file
-name of the JOnAS-specific XML deployment descriptor must be the file name of
-the standard XML deployment descriptor prefixed by 'jonas-'.
The parser gets the specified schema via the classpath (schemas are packaged -in the $JONAS_ROOT/lib/common/ow_jonas.jar file).
- -The standard deployment descriptor should contain structural information -for each enterprise bean that includes the following:
-The JOnAS-specific deployment descriptor contains information for each -enterprise bean including:
-<?xml version="1.0" encoding="ISO-8859-1"?> -<ejb-jar xmlns="http://java.sun.com/xml/ns/j2ee" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee - http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd" - version="2.1"> - <description>Here is the description of the test's beans</description> - <enterprise-beans> - <session> - <description>... Bean example one ...</description> - <display-name>Bean example one</display-name> - <ejb-name>ExampleOne</ejb-name> - <home>tests.Ex1Home</home> - <remote>tests.Ex1</remote> - <ejb-class>tests.Ex1Bean</ejb-class> - <session-type>Stateful</session-type> - <transaction-type>Container</transaction-type> - <env-entry> - <env-entry-name>name1</env-entry-name> - <env-entry-type>java.lang.String</env-entry-type> - <env-entry-value>value1</env-entry-value> - </env-entry> - <ejb-ref> - <ejb-ref-name>ejb/ses1</ejb-ref-name> - <ejb-ref-type>session</ejb-ref-type> - <home>tests.SS1Home</home> - <remote>tests.SS1</remote> - </ejb-ref> - <resource-ref> - <res-ref-name>jdbc/mydb</res-ref-name> - <res-type>javax.sql.DataSource</res-type> - <res-auth>Application</res-auth> - </resource-ref> - </session> - </enterprise-beans> - <assembly-descriptor> - <container-transaction> - <method> - <ejb-name>ExampleOne</ejb-name> - <method-name>*</method-name> - </method> - <trans-attribute>Required</trans-attribute> - </container-transaction> - <container-transaction> - <method> - <ejb-name>ExampleOne</ejb-name> - <method-inter>Home</ejb-name> - <method-name>*</method-name> - </method> - <trans-attribute>Supports</trans-attribute> - </container-transaction> - <container-transaction> - <method> - <ejb-name>ExampleOne</ejb-name> - <method-name>methodOne</method-name> - </method> - <trans-attribute>NotSupported</trans-attribute> - </container-transaction> - <container-transaction> - <method> - <ejb-name>ExampleOne</ejb-name> - <method-name>methodTwo</method-name> - <method-params><method-param>int</method-param></method-params> - </method> - <trans-attribute>Mandatory</trans-attribute> - </container-transaction> - <container-transaction> - <method> - <ejb-name>ExampleOne</ejb-name> - <method-name>methodTwo</method-name> - <method-params><method-param>java.lang.String</method-param></method-params> - </method> - <trans-attribute>NotSupported</trans-attribute> - </container-transaction> - </assembly-descriptor> -</ejb-jar> - - -<?xml version="1.0" encoding="ISO-8859-1"?> -<jonas-ejb-jar xmlns="http://www.objectweb.org/jonas/ns" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://www.objectweb.org/jonas/ns - http://www.objectweb.org/jonas/ns/jonas-ejb-jar_4_0.xsd" > - <jonas-session> - <ejb-name>ExampleOne</ejb-name> - <jndi-name>ExampleOneHome</jndi-name> - <jonas-ejb-ref> - <ejb-ref-name>ejb/ses1</ejb-ref-name> - <jndi-name>SS1Home_one</jndi-name> - </jonas-ejb-ref> - <jonas-resource> - <res-ref-name>jdbc/mydb</res-ref-name> - <jndi-name>jdbc_1</jndi-name> - </jonas-resource> - </jonas-session> -</jonas-ejb-jar> -- -
<?xml version="1.0" encoding="ISO-8859-1"?> -<ejb-jar xmlns="http://java.sun.com/xml/ns/j2ee" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee - http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd" - version="2.1"> - - <description>Here is the description of the test's beans</description> - <enterprise-beans> - <entity> - <description>... Bean example one ...</description> - <display-name>Bean example two</display-name> - <ejb-name>ExampleTwo</ejb-name> - <home>tests.Ex2Home</home> - <remote>tests.Ex2</remote> - <local-home>tests.Ex2LocalHome</local-home> - <local>tests.Ex2Local</local> - <ejb-class>tests.Ex2Bean</ejb-class> - <persistence-type>Container</persistence-type> - <prim-key-class>tests.Ex2PK</prim-key-class> - <reentrant>False</reentrant> - <cmp-version>1.x</cmp-version> - <cmp-field> - <field-name>field1</field-name> - </cmp-field> - <cmp-field> - <field-name>field2</field-name> - </cmp-field> - <cmp-field> - <field-name>field3</field-name> - </cmp-field> - <primkey-field>field3</primkey-field> - <env-entry> - <env-entry-name>name1</env-entry-name> - <env-entry-type>java.lang.String</env-entry-type> - <env-entry-value>value1</env-entry-value> - </env-entry> - </entity> - </enterprise-beans> - <assembly-descriptor> - <container-transaction> - <method> - <ejb-name>ExampleTwo</ejb-name> - <method-name>*</method-name> - </method> - <trans-attribute>Supports</trans-attribute> - </container-transaction> - </assembly-descriptor> -</ejb-jar> - - -<?xml version="1.0" encoding="ISO-8859-1"?> -<jonas-ejb-jar xmlns="http://www.objectweb.org/jonas/ns" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://www.objectweb.org/jonas/ns - http://www.objectweb.org/jonas/ns/jonas-ejb-jar_4_0.xsd" > - <jonas-entity> - <ejb-name>ExampleTwo</ejb-name> - <jndi-name>ExampleTwoHome</jndi-name> - <jndi-local-name>ExampleTwoLocalHome</jndi-local-name> - <jdbc-mapping> - <jndi-name>jdbc_1</jndi-name> - <jdbc-table-name>YourTable</jdbc-table-name> - <cmp-field-jdbc-mapping> - <field-name>field1</field-name> - <jdbc-field-name>dbf1</jdbc-field-name> - </cmp-field-jdbc-mapping> - <cmp-field-jdbc-mapping> - <field-name>field2</field-name> - <jdbc-field-name>dbf2</jdbc-field-name> - </cmp-field-jdbc-mapping> - <cmp-field-jdbc-mapping> - <field-name>field3</field-name> - <jdbc-field-name>dbf3</jdbc-field-name> - </cmp-field-jdbc-mapping> - <finder-method-jdbc-mapping> - <jonas-method> - <method-name>findByField1</method-name> - </jonas-method> - <jdbc-where-clause>where dbf1 = ?</jdbc-where-clause> - </finder-method-jdbc-mapping> - </jdbc-mapping> - </jonas-entity> -</jonas-ejb-jar> -- -
Although some characters, such as ">", are legal, it is good practice -to replace them with XML entity references.
- -The following is a list of the predefined entity references for XML:
- -| < | -< | -less than | -
| > | -> | -greater than | -
| & | -& | -ampersand | -
| ' | -' | -apostrophe | -
| " | -" | -quotation mark | -
The target audience for this guide is the Application Provider and -Assembler, i.e. the person in charge of combining one or more components -(ejb-jars and/or wars) to create a J2EE application. It describes how the -J2EE components should be packaged to create a J2EE application.
- -The content of this guide is the following:
- - -The application programmer is responsible for providing the deployment
-descriptor associated with the developed application (Enterprise ARchive).
-The Application Assembler's responsibilities is to provide a XML deployment
-descriptor that conforms to the deployment descriptor's XML schema as defined in
-the J2EE specification version 1.4. (Refer to
-$JONAS_ROOT/xml/application_1_4.xsd or
-http://java.sun.com/xml/ns/j2ee/application_1_4.xsd).
To deploy J2EE applications on the application server, all information is
-contained in one XML deployment descriptor. The file name for the application
-XML deployment descriptor is application.xml and it must be
-located in the top level META-INF directory.
The parser gets the specified schema via the classpath (schemas are packaged -in the $JONAS_ROOT/lib/common/ow_jonas.jar file).
- -Some J2EE application examples are provided in the JOnAS distribution:
-The standard deployment descriptor should contain structural information -that includes the following:
-There is no JOnAS-specific deployment descriptor for the Enterprise -ARchive.
- - - -<?xml version="1.0" encoding="UTF-8"?> - -<application xmlns="http://java.sun.com/xml/ns/j2ee" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee - http://java.sun.com/xml/ns/j2ee/application_1_4.xsd" - version="1.4"> - - <display-name>Simple example of application</display-name> - <description>Simple example</description> - - <module> - <ejb>ejb1.jar</ejb> - </module> - <module> - <ejb>ejb2.jar</ejb> - </module> - - <module> - <web> - <web-uri>web.war</web-uri> - <context-root>web</context-root> - </web> - </module> -</application> -- -
<?xml version="1.0" encoding="UTF-8"?> - -<application xmlns="http://java.sun.com/xml/ns/j2ee" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee - http://java.sun.com/xml/ns/j2ee/application_1_4.xsd" - version="1.4"> - - <display-name>Ear Security</display-name> - <description>Application with alt-dd and security</description> - <module> - <web> - <web-uri>admin.war</web-uri> - <context-root>admin</context-root> - </web> - </module> - <module> - <ejb>ejb.jar</ejb> - <alt-dd>altdd.xml</alt-dd> - </module> - <security-role> - <role-name>admin</role-name> - </security-role> -</application> -- -
Although some characters, such as ">", are legal, it is good practice -to replace them with XML entity references.
- -The following is a list of the predefined entity references for XML:
- -| < | -< | -less than | -
| > | -> | -greater than | -
| & | -& | -ampersand | -
| ' | -' | -apostrophe | -
| " | -" | -quotation mark | -
J2EE applications are packaged for deployment in a standard Java -programming language Archive file called an ear file (Enterprise -ARchive). This file can contain the following:
-Before building an ear file for a J2EE application, the ejb-jars and the -wars that will be packaged in the J2EE application must be built and the XML -deployment descriptor (application.xml) must be written.
- -Then, the ear file (<j2ee-application>.ear) can be
-built using the jar command:
cd <your_j2ee_application_directory> - jar cvf <j2ee-application>.ear * -- - diff --git a/jonas_doc/olddoc/PG_Entity.html b/jonas_doc/olddoc/PG_Entity.html deleted file mode 100644 index ea1cc2154a635de68b9d0dcfc33561531a351d6d..0000000000000000000000000000000000000000 --- a/jonas_doc/olddoc/PG_Entity.html +++ /dev/null @@ -1,2999 +0,0 @@ - - - - - -
The content of this guide is the following:
-The description of these elements is provided in the following -sections.
- -Note that in this documentation, the term "Bean" always means "Enterprise -Bean."
- -An entity bean represents persistent data. It is an object view of an -entity stored in a relational database. The persistence of an entity bean can -be handled in two ways:
-create methods:
-Finder methods are used to search for an EJB object or a collection of EJB -objects. The arguments of the method are used by the entity bean -implementation to locate the requested entity objects. For bean-managed -persistence, the bean provider is responsible for developing the -corresponding ejbFinder methods in the bean implementation. For -container-managed persistence, the bean provider does not write these -methods; they are generated at deployment time by the platform tools; the -description of the method is provided in the deployment descriptor, as -defined in the section "Configuring database -access for container-managed persistence." In the Home interface, the -finder methods must adhere to the following rules:
-home methods:
-create table ACCOUNT (ACCNO integer primary key, CUSTOMER varchar(30), -BALANCE number(15,4));
- -public interface AccountHome extends EJBHome {
- - public Account create(int accno, String
-customer, double balance)
- throws RemoteException,
-CreateException;
public Account findByPrimaryKey(Integer
-pk)
- throws RemoteException,
-FinderException;
public Account findByNumber(int accno)
-
- throws RemoteException,
-FinderException;
public Enumeration findLargeAccounts(double
-val)
- throws RemoteException,
-FinderException;
-}
The Component Interface is the client's view of an instance of the entity -bean. It is what is returned to the client by the Home interface after -creating or finding an entity bean instance. This interface contains the -business methods of the enterprise bean. The interface must extend the -javax.ejb.EJBObject interface if it is remote, or the -javax.ejb.EJBLocalObject if it is local. The methods of a remote -component interface must follow the rules for java RMI. For each method -defined in this component interface, there must be a matching method of the -bean implementation class (same arguments number and types, same return type, -same exceptions except for RemoteException).
- -<prim-key-class>java.lang.Integer</prim-key-class>-And, for container-managed persistence, the field which represents the -primary key: -
<primkey-field>accno</primkey-field>-The alternative way is to define its own Primary Key class, described as -follows: - -
The class must be serializable and must provide suitable implementation of -the hashcode() and equals(Object) methods.
- -For container-managed persistence, the following rules must be -followed:
-- public int accno; - -- -public AccountBeanPK(int accno) { this.accno = accno; }
- -public AccountBeanPK() { }
-
- public int hashcode() { return accno; }- -
- public boolean equals(Object other) { - --} - -- ...- }
There are two ways to manage the automatic primary key with JOnAS. The -first method is closer to what is described in the EJB specification, i.e. an -automatic PK is a hidden field, the type of which is not known even by the -application. The second method is to declare a usual PK CMP field of type -java.lang.Integer as automatic. The two cases are described below.
- -In this case, an automatic PK is a hidden field, the type of which is not -known even by the application. All that is necessary is to stipulate in the -standard deployment descriptor that this EJB has an automatic PK, by -specifying java.lang.Object as primkey-class. The primary key will be -completely hidden to the application (no CMP field, no getter/setter method). -This is valid for both CMP 2.x and CMP1 entity beans. The container will -create an internal CMP field and generate its value when the entity bean is -created.
- -Example:
- -Standard deployment descriptor:
-<entity> - ... - <ejb-name>AddressEJB</ejb-name> - <local-home>com.titan.address.AddressHomeLocal</local-home> - <local>com.titan.address.AddressLocal</local> - <ejb-class>com.titan.address.AddressBean</ejb-class> - <persistence-type>Container</persistence-type> - <prim-key-class>java.lang.Object</prim-key-class> - <reentrant>False</reentrant> - <cmp-version>2.x</cmp-version> - <abstract-schema-name>Cmp2_Address</abstract-schema-name> - <cmp-field><field-name>street</field-name></cmp-field> - <cmp-field><field-name>city</field-name></cmp-field> - <cmp-field><field-name>state</field-name></cmp-field> - <cmp-field><field-name>zip</field-name></cmp-field>- - - -
Address Bean Class extract:
- // Primary key is not explicitly initialized during ejbCreate method
- // No cmp field corresponds to the primary key
- public Integer ejbCreateAddress(String street, String city,
- String state, String zip ) throws javax.ejb.CreateException {
- setStreet(street);
- setCity(city);
- setState(state);
- setZip(zip);
- return null;
- }
-
-If nothing else is specified, and the JOnAS default CMP 2 database mapping -is used, the JOnAS container will generate a database column with name -JPK_ to handle this PK. However, it is possible to specify in -the JOnAS-specific Deployment Descriptor the name of the column that will be -used to store the PK value in the table, using the specific -<automatic-pk-field-name> element, as follows (this is necessary for -CMP2 legacy and for CMP1):
- -JOnAS-specific deployment descriptor:
-<jonas-ejb-jar xmlns="http://www.objectweb.org/jonas/ns" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://www.objectweb.org/jonas/ns http://www.objectweb.org/jonas/ns/jonas-ejb-jar_4_0.xsd" > - <jonas-entity> - <ejb-name>AddressEJB</ejb-name> - <jdbc-mapping> - <jndi-name>jdbc_1</jndi-name> - <automatic-pk-field-name>FieldPkAuto</automatic-pk-field-name> - </jdbc-mapping> - </jonas-entity>- -
The idea is to declare a usual PK CMP field of type java.lang.Integer as -automatic, then it no longer appears in create methods and its value is -automatically generated by the container at EJB instance creation time. But -it is still a cmp field, with getter/setter methods, accessible from the -application. Example:
- -In the standard DD, there is a usual primary key definition,
-<entity> - ... - <prim-key-class>java.lang.Integer</prim-key-class> - <cmp-field><field-name>id</field-name></cmp-field> - <primkey-field>id</primkey-field>- -
and in the JOnAS-specific Deployment Descriptor, it should be specified -that this PK is automatic,
-<jonas-entity> - ... - <jdbc-mapping> - - <automatic-pk>true</automatic-pk>-
-Note: The automatic primary key is given a unique ID -by an algorithm that is based on the system time; -therefore, IDs may be not sequential. -
--Important restriction: This algorithm will not work if used inside -a cluster with the same entity bean that is being managed in several jonas servers. -
-The first set of methods are those corresponding to the create and find -methods of the Home interface:
-This method is invoked by the container when a client invokes the - corresponding create operation on the enterprise Bean's home interface. - The method should initialize instance's variables from the input - arguments. The returned object should be the primary key of the created - instance. For bean-managed persistence, the bean provider should develop - here the JDBC code to create the corresponding data in the database. For - container-managed persistence, the container will perform the database - insert after the ejbCreate method completes and the return value - should be null.
-There is a matching ejbPostCreate method (same input parameters) for - each ejbCreate method. The container invokes this method after the - execution of the matching ejbCreate(...) method. During the ejbPostCreate - method, the object identity is available.
-The container invokes this method on a bean instance that is not - associated with any particular object identity (some kind of class method - ...) when the client invokes the corresponding method on the Home - interface. The implementation uses the arguments to locate the requested - object(s) in the database and returns a primary key (or a collection - thereof). Currently, collections will be represented as - java.util.Enumeration objects or - java.util.Collection. The mandatory FindByPrimaryKey - method takes as argument a primary key type value and returns a primary - key object (it verifies that the corresponding entity exists in the - database). For container-managed persistence, the bean provider - does not have to write these finder methods; they are generated at - deployment time by the EJB platform tools. The information needed by the - EJB platform for automatically generating these finder methods should be - provided by the bean programmer. The EJB 1.1 specification does not - specify the format of this finder method description; for JOnAS, - the CMP 1.1 finder methods description should be provided in the - JOnAS-specific deployment descriptor of the Entity Bean (as an SQL - query). Refer to the section "Configuring - database access for container-managed persistence." The EJB 2.0 - specification defines a standard way to describe these finder methods, - i.e. in the standard deployment descriptor, as an EJB-QL query. Also - refer to the section "Configuring - database access for container-managed persistence." Then, the methods - of the javax.ejb.EntityBean interface must be implemented:
-Used by the container to pass a reference to the EntityContext to - the bean instance. The container invokes this method on an instance - after the instance has been created. Generally, this method is used - to store this reference in an instance variable.
-Unset the associated entity context. The container calls this - method before removing the instance. This is the last method the - container invokes on the instance.
-The container invokes this method when the instance is taken out - of the pool of available instances to become associated with a - specific EJB object. This method transitions the instance to the - ready state.
-The container invokes this method on an instance before the - instance becomes dissociated with a specific EJB object. After this - method completes, the container will place the instance into the pool - of available instances.
-This method is invoked by the container when a client invokes a - remove operation on the enterprise bean. For entity beans with - bean-managed persistence, this method should contain the JDBC - code to remove the corresponding data in the database. For - container-managed persistence, this method is called - before the container removes the entity representation in the - database.
-The container invokes this method to instruct the instance to - synchronize its state by loading it from the underlying database. For - bean-managed persistence, the EJB provider should code at this - location the JDBC statements for reading the data in the database. - For container-managed persistence, loading the data from the - database will be done automatically by the container just - before ejbLoad is called, and the ejbLoad method should only - contain some "after loading calculation statements."
-The container invokes this method to instruct the instance to - synchronize its state by storing it to the underlying database. For - bean-managed persistence, the EJB provider should code at this - location the JDBC statements for writing the data in the database. - For entity beans with container-managed persistence, this - method should only contain some "pre-store statements," since the - container will extract the container-managed fields and write them to - the database just after the ejbStore method call.
- -The following examples are for container-managed persistence with EJB 1.1 -and EJB 2.0. For bean-managed persistence, refer to the examples delivered -with your specific platform.
- -CMP 1.1
-package eb;
-
-import java.rmi.RemoteException;
-import javax.ejb.EntityBean;
-import javax.ejb.EntityContext;
-import javax.ejb.ObjectNotFoundException;
-import javax.ejb.RemoveException;
-import javax.ejb.EJBException;
-
-public class AccountImplBean implements EntityBean {
-
- // Keep the reference on the EntityContext
- protected EntityContext entityContext;
-
- // Object state
- public Integer accno;
- public String customer;
- public double balance;
-
- public Integer ejbCreate(int val_accno, String val_customer, double val_balance) {
-
- // Init object state
- accno = new Integer(val_accno);
- customer = val_customer;
- balance = val_balance;
- return null;
- }
-
- public void ejbPostCreate(int val_accno, String val_customer, double val_balance) {
- // Nothing to be done for this simple example.
- }
-
- public void ejbActivate() {
- // Nothing to be done for this simple example.
- }
-
- public void ejbLoad() {
- // Nothing to be done for this simple example, in implicit persistence.
- }
-
- public void ejbPassivate() {
- // Nothing to be done for this simple example.
- }
-
-
- public void ejbRemove() {
- // Nothing to be done for this simple example, in implicit persistence.
- }
-
- public void ejbStore() {
- // Nothing to be done for this simple example, in implicit persistence.
- }
-
- public void setEntityContext(EntityContext ctx) {
- // Keep the entity context in object
- entityContext = ctx;
- }
-
- public void unsetEntityContext() {
- entityContext = null;
- }
-
- public double getBalance() {
- return balance;
- }
-
- public void setBalance(double d) {
- balance = balance + d;
- }
-
- public String getCustomer() {
- return customer;
- }
-
- public void setCustomer(String c) {
- customer = c;
- }
-
- public int getNumber() {
- return accno.intValue();
- }
-}
-CMP 2.0
-import java.rmi.RemoteException;
-import javax.ejb.EntityBean;
-import javax.ejb.EntityContext;
-import javax.ejb.ObjectNotFoundException;
-import javax.ejb.RemoveException;
-import javax.ejb.CreateException;
-import javax.ejb.EJBException;
-
-public abstract class AccountImpl2Bean implements EntityBean {
-
- // Keep the reference on the EntityContext
- protected EntityContext entityContext;
-
-
- /*========================= Abstract set and get accessors for cmp fields ==============*/
-
- public abstract String getCustomer();
- public abstract void setCustomer(String customer);
-
- public abstract double getBalance();
- public abstract void setBalance(double balance);
-
- public abstract int getAccno();
- public abstract void setAccno(int accno);
-
- /*========================= ejbCreate methods ============================*/
-
-
- public Integer ejbCreate(int val_accno, String val_customer, double val_balance)
- throws CreateException {
-
- // Init object state
- setAccno(val_accno);
- setCustomer(val_customer);
- setBalance(val_balance);
- return null;
- }
-
- public void ejbPostCreate(int val_accno, String val_customer, double val_balance) {
- // Nothing to be done for this simple example.
- }
-
-
- /*====================== javax.ejb.EntityBean implementation =================*/
-
- public void ejbActivate() {
- // Nothing to be done for this simple example.
- }
-
- public void ejbLoad() {
- // Nothing to be done for this simple example, in implicit persistence.
- }
-
- public void ejbPassivate() {
- // Nothing to be done for this simple example.
- }
-
- public void ejbRemove() throws RemoveException {
- // Nothing to be done for this simple example, in implicit persistence.
- }
-
- public void ejbStore() {
- // Nothing to be done for this simple example, in implicit persistence.
- }
-
- public void setEntityContext(EntityContext ctx) {
-
- // Keep the entity context in object
- entityContext = ctx;
- }
-
- public void unsetEntityContext() {
- entityContext = null;
- }
-
- /**
- * Business method to get the Account number
- */
- public int getNumber() {
- return getAccno();
- }
-
-}
-
-public void doSomethingInDB (...) {
- conn = dataSource.getConnection();
- ... // Database access operations
- conn.close();
-}
-A DataSource object associates a JDBC driver with a database (as an ODBC
-datasource). It is created and registered in JNDI by the EJB server at launch
-time (refer also to the section "JDBC DataSources configuration").
-
-A DataSource object is a resource manager connection factory for -java.sql.Connection objects, which implements connections to a -database management system. The enterprise bean code refers to resource -factories using logical names called "Resource manager connection factory -references." The resource manager connection factory references are special -entries in the enterprise bean environment. The bean provider must use -resource manager connection factory references to obtain the datasource -object as follow:
-<resource-ref> -<res-ref-name>jdbc/AccountExplDs</res-ref-name> -<res-type>javax.sql.DataSource</res-type> -<res-auth>Container</res-auth> -</resource-ref>-The <res-auth> element indicates which of the two resource manager -authentication approaches is used: -
<jonas-entity> - <ejb-name>AccountExpl</ejb-name> - <jndi-name>AccountExplHome</jndi-name> - <jonas-resource> - <res-ref-name>jdbc/AccountExplDs</res-ref-name> - <jndi-name>jdbc_1</jndi-name> - </jonas-resource> - </jonas-entity>-The ejbStore method of the same Account example with bean-managed persistence -is shown in the following example. It performs JDBC operations to update the -database record representing the state of the entity bean instance. The JDBC -connection is obtained from the datasource associated with the bean. This -datasource has been instantiated by the EJB server and is available for the -bean through its resource reference name, which is defined in the standard -deployment descriptor. - -
In the bean, a reference to a datasource object of the EJB server is -initialized:
- -it = new InitialContext();
- -ds = -(DataSource)it.lookup("java:comp/env/jdbc/AccountExplDs");
- -Then, this datasource object is used in the implementation of the methods -performing JDBC operations, such as ejbStore, as illustrated in the -following:
-public void ejbStore
- Connection conn = null;
- PreparedStatement stmt = null;
- try { // get a connection
- conn = ds.getConnection();
- // store Object state in DB
- stmt = conn.prepareStatement("update account set customer=?,balance=? where accno=?");
- stmt.setString(1, customer);
- stmt.setDouble(2, balance);
- Integer pk = (Integer)entityContext.getPrimaryKey();
- stmt.setInt(3, pk.accno);
- stmt.executeUpdate();
- } catch (SQLException e) {
- throw new javax.ejb.EJBException("Failed to store bean to database", e);
- } finally {
- try {
- if (stmt != null) stmt.close(); // close statement
- if (conn != null) conn.close(); // release connection
- } catch (Exception ignore) {}
- }
-}
-Note that the close statement instruction may be important if the server is
-intensively accessed by many clients performing entity bean access. If the
-statement is not closed in the finally block, since stmt is in the
-scope of the method, it will be deleted at the end of the method (and the
-close will be implicitly done). However, it may be some time before the Java
-garbage collector deletes the statement object. Therefore, if the number of
-clients performing entity bean access is important, the DBMS may raise a "too
-many opened cursors" exception (a JDBC statement corresponds to a DBMS
-cursor). Since connection pooling is performed by the platform, closing the
-connection will not result in a physical connection close, therefore opened
-cursors will not be closed. Thus, it is preferable to explicitly close the
-statement in the method.
-
-It is a good programming practice to put the JDBC connection and JDBC -statement close operations in a finally bloc of the try statement.
- -<persistence-type>container</persistence-type> - <cmp-version>1.x</cmp-version> - <cmp-field> - <field-name>fieldOne</field-name> - </cmp-field> - <cmp-field> - <field-name>fieldTwo</field-name> - </cmp-field>-With container-managed persistence the programmer need not develop the -code for accessing the data in the relational database; this code is included -in the container itself (generated by the platform tools). However, for the -EJB platform to know how to access the database and which data to read and -write in the database, two types of information must be provided with the -bean: -
For CMP 1.1, the bean deployer is responsible for defining the mapping of -the bean fields to the database table columns. The name of the DataSource can -be set at deployment time, since it depends on the EJB platform -configuration. This database configuration information is defined in the -JOnAS-specific deployment descriptor via the jdbc-mapping element. -The following example defines the mapping for a CMP 1.1 entity bean:
-<jdbc-mapping> - <jndi-name>jdbc_1</jndi-name> - <jdbc-table-name>accountsample</jdbc-table-name> - <cmp-field-jdbc-mapping> - <field-name>mAccno</field-name> - <jdbc-field-name>accno</jdbc-field-name> - </cmp-field-jdbc-mapping> - <cmp-field-jdbc-mapping> - <field-name>mCustomer</field-name> - <jdbc-field-name>customer</jdbc-field-name> - </cmp-field-jdbc-mapping> - <cmp-field-jdbc-mapping> - <field-name>mBalance</field-name> - <jdbc-field-name>balance</jdbc-field-name> - </jdbc-mapping>-jdbc_1 is the JNDI name of the DataSource object identifying the -database. accountsample is the name of the table used to store the -bean instances in the database. mAccno, mCustomer, and -mBalance are the names of the container-managed fields of the bean -to be stored in the accno, customer, and balance -columns of the accountsample table. This example applies to -container-managed persistence. For bean-managed persistence, -the database mapping does not exist. - -
For a CMP 2.0 entity bean, only the jndi-name element of the -jdbc-mapping is mandatory, since the mapping may be generated -automatically (for an explicit mapping definition, refer to the "JOnAS Database Mapping" section of the Using CMP2.0 persistence chapter):
-- <jdbc-mapping> - <jndi-name>jdbc_1</jndi-name> - </jdbc-mapping> - <cleanup>create</cleanup> --For a CMP 2.0 entity bean, the JOnAS-specific deployment descriptor contains -an additional element, cleanup, at the same level as the -jdbc-mapping element, which can have one of the following values: -
For each finder method, this element provides a way to define an SQL WHERE -clause that will be used in the generated finder method implementation to -query the relational table storing the bean entities. Note that the table -column names should be used, not the bean field names. Example:
-<finder-method-jdbc-mapping> - <jonas-method> - <method-name>findLargeAccounts</method-name> - </jonas-method> - <jdbc-where-clause>where balance > ?</jdbc-where-clause> - </finder-method-jdbc-mapping>-The previous finder method description will cause the platform tools to -generate an implementation of ejbFindLargeAccount(double arg) that returns -the primary keys of the entity bean objects corresponding to the tuples -returned by the "select ... from Account where balance > ?", where '?' -will be replaced by the value of the first argument of the findLargeAccount -method. If several '?' characters appear in the provided WHERE clause, this -means that the finder method has several arguments and the '?' characters -will correspond to these arguments, adhering to the order of the method -signature. - -
In the WHERE clause, the parameters can be followed by a number, which
-specifies the method parameter number that will be used by the query in this
-position.
-Example: The WHERE clause of the following finder method can be:
Enumeration findByTextAndDateCondition(String text, java.sql.Date date) - - WHERE (description like ?1 OR summary like ?1) AND (?2 > date)-Note that a <finder-method-jdbc-mapping> element for the -findByPrimaryKey method is not necessary, since the meaning of this -method is known. - -
Additionally, note that for CMP 2.0, the information defining the -behaviour of the implementation of a find<method> method is -located in the standard deployment descriptor, as an EJB-QL query -(i.e. this is not JOnAS-specific information). The same finder method example -in CMP 2.0:
-<query> - <query-method> - <method-name>findLargeAccounts</method-name> - <method-params> - <method-param>double</method-param> - </method-params> - </query-method> - <ejb-ql>SELECT OBJECT(o) FROM accountsample o WHERE o.balance > ?1</ejb-ql> - </query>-The datatypes supported for container-managed fields in CMP 1.1 are the -following:
| Java Type | -JDBC Type | -JDBC driver Access methods | -
| boolean | -BIT | -getBoolean(), setBoolean() | -
| byte | -TINYINT | -getByte(), setByte() | -
| short | -SMALLINT | -getShort(), setShort() | -
| int | -INTEGER | -getInt(), setInt() | -
| long | -BIGINT | -getLong(), setLong() | -
| float | -FLOAT | -getFloat(), setFloat() | -
| double | -DOUBLE | -getDouble(), setDouble | -
| byte[] | -VARBINARY or LONGVARBINARY (1) | -getBytes(), setBytes() | -
| java.lang.String | -VARCHAR or LONGVARCHAR (1) | -getString(), setString() | -
| java.lang.Boolean | -BIT | -getBoolean(), setObject() | -
| java.lang.Integer | -INTEGER | -getInt(), setObject() | -
| java.lang.Short | -SMALLINT | -getShort(), setObject() | -
| java.lang.Long | -BIGINT | -getLong(), setObject() | -
| java.lang.Float | -REAL | -getFloat(), setObject() | -
| java.lang.Double | -DOUBLE | -getDouble(), setObject() | -
| java.math.BigDecimal | -NUMERIC | -getBigDecimal(), setObject() | -
| java.math.BigInteger | -NUMERIC | -getBigDecimal(), setObject() | -
| java.sql.Date | -DATE | -getDate(), setDate() | -
| java.sql.Time | -TIME | -getTime(), setTime() | -
| java.sql.Timestamp | -TIMESTAMP | -getTimestamp(), setTimestamp() | -
| any serializable class | -VARBINARY or LONGVARBINARY (1) | -getBytes(), setBytes() | -
(1) The mapping for String will normally be VARCHAR, but will turn into -LONGVARCHAR if the given value exceeds the driver's limit on VARCHAR values. -The case is similar for byte[] and VARBINARY and LONGVARBINARY values.
- -For CMP 2.0, the supported datatypes depend on the JORM mapper used.
- - -$JONAS_ROOT/xml/jonas-ejb-jar_4_7.xsd for a complete description
-of the JOnAS-specific deployment descriptor.
-
-Note that if several of these elements are used, they should appear in the -following order within the <jonas-entity> element:
-Important: If CMP1 beans are deployed, only the following policies should be used: -
Important note:
-Note that this is useless with CMP2 entity beans, since this will be done -automatically by the container.
- -The bean implementation manages a boolean isDirty and implements -a method that returns the value of this boolean: isModified
-
- private transient boolean isDirty;
- public boolean isModified() {
- return isDirty;
- }
-
-
-The JOnAS-specific deployment descriptor directs the bean to implement an -isModified method:
-- <jonas-entity> - <ejb-name>Item</ejb-name> - <is-modified-method-name>isModified</is-modified-method-name> - ..... - </jonas-entity> -- -
Methods that modify the value of the bean must set the flag
-isDirty to true.
-Methods that restore the value of the bean from the database must reset the
-flag isDirty to false. Therefore, the flag must be set to
-false in the ejbLoad() and ejbStore() methods.
<jonas-entity> - <ejb-name>Item</ejb-name> - <passivation-timeout>5</passivation-timeout> - ..... - </jonas-entity> --This entity bean will be passivated every five second, if not accessed within -transactions. - - -
This section highlights the main differences between CMP as defined in EJB -2.0 specification (called CMP2.0) and CMP as defined in EJB 1.1 specification -(called CMP1.1). Major new features in the standard development and -deployment of CMP2.0 entity beans are listed (comparing them to CMP1.1), -along with JOnAS-specific information. Mapping CMP2.0 entity beans to the -database is described in detail. Note that the database mapping can be -created entirely by JOnAS, in which case the JOnAS-specific deployment -descriptor for an entity bean should contain only the datasource and the -element indicating how the database should be initialized.
- -This section briefly describes the new features available in CMP2.0 as -compared to CMP 1.1, and how these features change the development of entity -beans.
- -The EJB implementation class 1) implements the bean's business methods of -the component interface, 2) implements the methods dedicated to the EJB -environment (the interface of which is explicitly defined in the EJB -specification), and 3) defines the abstract methods representing both the -persistent fields (cmp-fields) and the relationship fields (cmr-fields). The -class must implement the javax.ejb.EntityBean interface, be defined -as public, and be abstract (which is not the case for CMP1.1, where it must -not be abstract). The abstract methods are the get and set accessor methods -of the bean cmp and cmr fields. Refer to the examples and details in the -section "Developing Entity Beans" of -the JOnAS documentation.
- -The standard way to indicate to an EJB platform that an entity bean has -container-managed persistence is to fill the -<persistence-type> tag of the deployment descriptor with the -value "container," and to fill the <cmp-field> tags of the -deployment descriptor with the list of container-managed fields (the fields -that the container will have in charge to make persistent) and the -<cmr-field> tags identifying the relationships. The CMP -version (1.x or 2.x) should also be specified in the <cmp-version> tag. -This is represented by the following lines in the deployment descriptor:
-<persistence-type>container</persistence-type> - <cmp-version>1.x</cmp-version> - <cmp-field> - <field-name>fieldOne</field-name> - </cmp-field> - <cmp-field> - <field-name>fieldTwo</field-name> - </cmp-field> -- -
Note that for running CMP1.1-defined entity beans on an EJB2.0 platform, -such as JOnAS 3.x, you must introduce this -<cmp-version> element in your deployment descriptors, since the -default cmp-version value (if not specified) is 2.x.
- -Note that for CMP 2.0, the information defining the behaviour of the -implementation of a find<method> method is located in -the standard deployment descriptor as an EJB-QL query (this -is not JOnAS-specific information). -For CMP 1.1, this information is located in the JOnAS-specific deployment -descriptor as an SQL WHERE clause specified in a -<finder-method-jdbc-mapping> element.
- -Finder method example in CMP 2.0: for a findLargeAccounts(double -val) method defined on the Account entity bean of the JOnAS eb -example.
-<query> - <query-method> - <method-name>findLargeAccounts</method-name> - <method-params> - <method-param>double</method-param> - </method-params> - </query-method> - <ejb-ql>SELECT OBJECT(o) FROM accountsample o WHERE o.balance > ?1</ejb-ql> - </query> -- -
The LIMIT feature has been added to the standard EJBQL -query language. This feature enables you to retrieve just a portion -of the results generated by the rest of a query.
- -The syntax of the LIMIT clause is:
-- limit_clause ::= LIMIT limit_expression (, limit_expression )? - limit_expression ::= integer_literal | input_parameter --
The first limit_expression corresponds to the start_at range and the second one to the size range.
- -The limit_clause is the last clause of the query:
-- ejbql ::= select_clause from_clause [where_clause] [orderby_clause] [limit_clause] --
Example:
-- SELECT OBJECT(c) FROM jt2_Customer AS c ORDER BY c.id LIMIT ?1, 20 --
Note that this feature is currently not implemented on all the database types supported by JORM/MEDOR.
- -For implementing the EJB 2.0 persistence (CMP2.0), JOnAS relies on the JORM framework. JORM -itself relies on JOnAS DataSources (specified in DataSource properties files) -for connecting to the actual database. JORM must adapt its object-relational -mapping to the underlying database, for which it makes use of adapters called -"mappers." Thus, for each type of database (and more precisely for each JDBC -driver), the corresponding mapper must be specified in the DataSource. This -is the purpose of the datasource.mapper property of the -DataSource properties file. Note that all JOnAS-provided DataSource -properties files (in JOnAS_ROOT/conf) already contain this property with the -correct mapper.
- -| property name | -description | -possible values | -
|---|---|---|
| datasource.mapper | -JORM database mapper | -
|
-
Contact the JOnAS team to obtain a mapper for other databases.
- -The container code generated at deployment is now independent of the JORM mappers. -Until JOnAS 4.1.4, the container code generated at deployment (GenIC or ejbjar ant task) -was dependent on this mapper. It was possible to deploy (generate container code) -a bean for several mappers in order to change the database (i.e. the -DataSource file) without redeploying the bean. These mappers were -specified as the mappernames argument of the GenIC command -or as the mappernames attribute of the JOnAS ANT ejbjar -task. The value was a comma-separated list of mapper names for which the -container classes were generated. These mappernames options are now -deprecated.
- - -The mapping to the database of entity beans and their relationships may be -specified in the JOnAS-specific deployment descriptor, in -jonas-entity elements, and in jonas-ejb-relation elements. -Since JOnAS is able to generate the database mapping, all the elements of the -JOnAS-specific deployment descriptor defined in this section (which are -sub-elements of jonas-entity or jonas-ejb-relation) are -optional, except those for specifying the datasource and the initialization -mode (i.e. the jndi-name of jdbc-mapping and -cleanup). The default values of these mapping elements, provided in -this section, define the JOnAS-generated database mapping.
- -For specifying the database within which a CMP 2.0 entity bean is stored, -the jndi-name element of the jdbc-mapping is necessary. -This is the JNDI name of the DataSource representing the database storing the -entity bean.
-<jdbc-mapping> - <jndi-name>jdbc_1</jndi-name> - </jdbc-mapping> -- -
For a CMP 2.0 entity bean, the JOnAS-specific deployment descriptor -contains an additional element, cleanup, to be specified before the -jdbc-mapping element, which can have one of the following values:
-It may be useful for testing purposes to delete the database data each -time a bean is loaded. For this purpose, the part of the JOnAS-specific -deployment descriptor related to the entity bean may look like the -following:
-<cleanup>removedata</cleanup> - <jdbc-mapping> - <jndi-name>jdbc_1</jndi-name> - </jdbc-mapping> -- -
Mapping CMP fields in CMP2.0 is similar to that of CMP 1.1, but in CMP2.0 -it is also possible to specify the SQL type of a column. Usually this SQL -type is used if JOnAS creates the table (create value of the -cleanup element), and if the JORM default chosen SQL type is not -appropriate.
- -..... - <entity> - <ejb-name>A</ejb-name> - ..... - <cmp-field> - <field-name>idA</field-name> - </cmp-field> - <cmp-field> - <field-name>f</field-name> - </cmp-field> - ..... - </entity> - ..... -- -
| t_A | -- |
| c_idA | -c_f | -
| ... | -... | -
..... - <jonas-entity> - <ejb-name>A</ejb-name> - ..... - <jdbc-mapping> - <jndi-name>jdbc_1</jndi-name> - <jdbc-table-name>t_A</jdbc-table-name> - <cmp-field-jdbc-mapping> - <field-name>idA</field-name> - <jdbc-field-name>c_idA</jdbc-field-name> - </cmp-field-jdbc-mapping> - <cmp-field-jdbc-mapping> - <field-name>f</field-name> - <jdbc-field-name>c_f</jdbc-field-name> - <sql-type>varchar(40)</sql-type> - </cmp-field-jdbc-mapping> - </jdbc-mapping> - ..... - </jonas-entity> - ..... -- -
Defaults values:
- -| jndi-name | -Mandatory | -
| jdbc-table-name | -Optional. - Default value is the upper-case CMP2 abstract-schema-name, - or the CMP1 ejb-name, suffixed by - _. |
-
| cmp-field-jdbc-mapping | -Optional. | -
| jdbc-field-name | -Optional. - Default value is the field-name suffixed by _. - idA_ and f_ in the example. |
-
| sql-type | -Optional. - Default value defined by JORM. |
-
..... - <entity> - <ejb-name>A</ejb-name> - ..... - <cmp-field> - <field-name>idA</field-name> - </cmp-field> - <primkey-field>idA</primkey-field> - ..... - </entity> - ..... - <entity> - <ejb-name>B</ejb-name> - ..... - <cmp-field> - <field-name>idB</field-name> - </cmp-field> - <primkey-field>idB</primkey-field> - ..... - </entity> - ..... - <relationships> - <ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <ejb-relationship-role> - <!-- A => B --> - <ejb-relationship-role-name>a2b</ejb-relationship-role-name> - <multiplicity>One</multiplicity> - <relationship-role-source> - <ejb-name>A</ejb-name> - </relationship-role-source> - <cmr-field> - <cmr-field-name>b</cmr-field-name> - </cmr-field> - </ejb-relationship-role> - <ejb-relationship-role> - <!-- B => A --> - <ejb-relationship-role-name>b2a</ejb-relationship-role-name> - <multiplicity>One</multiplicity> - <relationship-role-source> - <ejb-name>B</ejb-name> - </relationship-role-source> - </ejb-relationship-role> - </ejb-relation> - </relationships> - ..... -- -
-
|
-
-
|
-
There is a foreign key in the table of the bean that owns the CMR -field.
- -..... - <jonas-entity> - <ejb-name>A</ejb-name> - ..... - <jdbc-mapping> - <jndi-name>jdbc_1</jndi-name> - <jdbc-table-name>t_A/jdbc-table-name> - <cmp-field-jdbc-mapping> - <field-name>idA</field-name> - <jdbc-field-name>c_idA</jdbc-field-name> - </cmp-field-jdbc-mapping> - </jdbc-mapping> - ..... - </jonas-entity> - ..... - <jonas-entity> - <ejb-name>B</ejb-name> - ..... - <jdbc-mapping> - <jndi-name>jdbc_1</jndi-name> - <jdbc-table-name>t_B/jdbc-table-name> - <cmp-field-jdbc-mapping> - <field-name>idB</field-name> - <jdbc-field-name>c_idB</jdbc-field-name> - </cmp-field-jdbc-mapping> - </jdbc-mapping> - ..... - </jonas-entity> - ..... - <jonas-ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <jonas-ejb-relationship-role> - <ejb-relationship-role-name>a2b</ejb-relationship-role-name> - <foreign-key-jdbc-mapping> - <foreign-key-jdbc-name>cfk_idb</foreign-key-jdbc-name> - </foreign-key-jdbc-mapping> - </jonas-ejb-relationship-role> - </jonas-ejb-relation> - ..... -- -
foreign-key-jdbc-name is the column name of the foreign key in the
-table of the source bean of the relationship-role.
-In this example, where the destination bean has a primary-key-field, it is
-possible to deduce that this foreign-key-jdbc-name column is to be associated
-with the column of this primary-key-field in the table of the destination
-bean.
Default values:
- -| jonas-ejb-relation | -Optional | -
| foreign-key-jdbc-name | -Optional. - Default value is the abstract-schema-name of the destination bean, - suffixed by _, and by its primary-key-field. - B_idb in the example. |
-
Compared to 1-1 unidirectional relationships, there is a CMR field in both -of the beans, thus making two types of mapping possible.
- -..... - <relationships> - <ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <ejb-relationship-role> - <!-- A => B --> - <ejb-relationship-role-name>a2b</ejb-relationship-role-name> - <multiplicity>One</multiplicity> - <relationship-role-source> - <ejb-name>A</ejb-name> - </relationship-role-source> - <cmr-field> - <cmr-field-name>b</cmr-field-name> - </cmr-field> - </ejb-relationship-role> - <ejb-relationship-role> - <!-- B => A --> - <ejb-relationship-role-name>b2a</ejb-relationship-role-name> - <multiplicity>One</multiplicity> - <relationship-role-source> - <ejb-name>B</ejb-name> - </relationship-role-source> - <cmr-field> - <cmr-field-name>a</cmr-field-name> - </cmr-field> - </ejb-relationship-role> - </ejb-relation> - </relationships> - ..... -- -
Two mappings are possible. One of the tables may hold a foreign key.
- -Case 1:
- -
-
|
-
-
|
-
Case 2:
- -
-
|
-
-
|
-
Case 1:
-..... - <jonas-ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <jonas-ejb-relationship-role> - <ejb-relationship-role-name>a2b</ejb-relationship-role-name> - <foreign-key-jdbc-mapping> - <foreign-key-jdbc-name>cfk_idb</foreign-key-jdbc-name> - </foreign-key-jdbc-mapping> - </jonas-ejb-relationship-role> - </jonas-ejb-relation> - ..... -- -
Case 2:
-..... - <jonas-ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <jonas-ejb-relationship-role> - <ejb-relationship-role-name>b2a</ejb-relationship-role-name> - <foreign-key-jdbc-mapping> - <foreign-key-jdbc-name>cfk_ida</foreign-key-jdbc-name> - </foreign-key-jdbc-mapping> - </jonas-ejb-relationship-role> - </jonas-ejb-relation> - ..... -- -
For the default mapping, the foreign key is in the table of the source -bean of the first ejb-relationship-role of the ejb-relation. In the example, -the default mapping corresponds to case 1, since the ejb-relationship-role -a2b is the first defined in the ejb-relation a-b. Then, the -default values are similar to those of the 1-1 unidirectional -relationship.
- - -..... - <relationships> - <ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <ejb-relationship-role> - <!-- A => B --> - <ejb-relationship-role-name>a2b</ejb-relationship-role-name> - <multiplicity>One</multiplicity> - <relationship-role-source> - <ejb-name>A</ejb-name> - </relationship-role-source> - <cmr-field> - <cmr-field-name>b</cmr-field-name> - <cmr-field-type>java.util.Collection</cmr-field-type> - </cmr-field> - </ejb-relationship-role> - <ejb-relationship-role> - <!-- B => A --> - <ejb-relationship-role-name>b2a</ejb-relationship-role-name> - <multiplicity>Many</multiplicity> - <relationship-role-source> - <ejb-name>B</ejb-name> - </relationship-role-source> - </ejb-relationship-role> - </ejb-relation> - </relationships> - ..... -- -
-
|
-
-
|
-
In this case, the foreign key must be in the table of the bean which is on -the "many" side of the relationship (i.e. in the table of the source bean of -the relationship role with multiplicity many), t_B.
- -..... - <jonas-ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <jonas-ejb-relationship-role> - <ejb-relationship-role-name>b2a</ejb-relationship-role-name> - <foreign-key-jdbc-mapping> - <foreign-key-jdbc-name>cfk_ida</foreign-key-jdbc-name> - </foreign-key-jdbc-mapping> - </jonas-ejb-relationship-role> - </jonas-ejb-relation> - ..... -- -
Default values:
- -| jonas-ejb-relation | -Optional | -
| foreign-key-jdbc-name | -Optional. - Default value is the abstract-schema-name of the destination bean of - the "one" side of the relationship (i.e. the source bean of the - relationship role with multiplicity one), suffixed by _, and - by its primary-key-field. - A_ida in the example. |
-
Similar to 1-N unidirectional relationships, but with a CMR field in each -bean.
- -..... - <relationships> - <ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <ejb-relationship-role> - <!-- A => B --> - <ejb-relationship-role-name>a2b</ejb-relationship-role-name> - <multiplicity>One</multiplicity> - <relationship-role-source> - <ejb-name>A</ejb-name> - </relationship-role-source> - <cmr-field> - <cmr-field-name>b</cmr-field-name> - <cmr-field-type>java.util.Collection</cmr-field-type> - </cmr-field> - </ejb-relationship-role> - <ejb-relationship-role> - <!-- B => A --> - <ejb-relationship-role-name>b2a</ejb-relationship-role-name> - <multiplicity>Many</multiplicity> - <relationship-role-source> - <ejb-name>B</ejb-name> - </relationship-role-source> - <cmr-field> - <cmr-field-name>a</cmr-field-name> - </cmr-field> - </ejb-relationship-role> - </ejb-relation> - </relationships> - ..... -- -
-
|
-
-
|
-
In this case, the foreign key must be in the table of the bean which is on -the "many" side of the relationship (i.e. in the table of the source bean of -the relationship role with multiplicity many), t_B.
- -..... - <jonas-ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <jonas-ejb-relationship-role> - <ejb-relationship-role-name>b2a</ejb-relationship-role-name> - <foreign-key-jdbc-mapping> - <foreign-key-jdbc-name>cfk_ida</foreign-key-jdbc-name> - </foreign-key-jdbc-mapping> - </jonas-ejb-relationship-role> - </jonas-ejb-relation> - ..... -- -
Default values:
- -| jonas-ejb-relation | -Optional | -
| foreign-key-jdbc-name | -Optional. - Default value is the abstract-schema-name of the destination bean of - the "one" side of the relationship (i.e. the source bean of the - relationship role with multiplicity one), suffixed by _, and - by its primary-key-field. - A_ida in the example. |
-
Similar to 1-N unidirectional relationships, but the CMR field is defined -on the "many" side of the relationship, i.e. on the (source bean of the) -relationship role with multiplicity "many."
- -..... - <relationships> - <ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <ejb-relationship-role> - <!-- A => B --> - <ejb-relationship-role-name>a2b</ejb-relationship-role-name> - <multiplicity>Many</multiplicity> - <relationship-role-source> - <ejb-name>A</ejb-name> - </relationship-role-source> - <cmr-field> - <cmr-field-name>b</cmr-field-name> - </cmr-field> - </ejb-relationship-role> - <ejb-relationship-role> - <!-- B => A --> - <ejb-relationship-role-name>b2a</ejb-relationship-role-name> - <multiplicity>One</multiplicity> - <relationship-role-source> - <ejb-name>B</ejb-name> - </relationship-role-source> - </ejb-relationship-role> - </ejb-relation> - </relationships> - ..... -- -
-
|
-
-
|
-
In this case, the foreign key must be in the table of the bean which is on -the "many" side of the relationship (i.e. in table of the source bean of the -relationship role with multiplicity many), t_A.
- -..... - <jonas-ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <jonas-ejb-relationship-role> - <ejb-relationship-role-name>a2b</ejb-relationship-role-name> - <foreign-key-jdbc-mapping> - <foreign-key-jdbc-name>cfk_idb</foreign-key-jdbc-name> - </foreign-key-jdbc-mapping> - </jonas-ejb-relationship-role> - </jonas-ejb-relation> - ..... -- -
Default values:
- -| jonas-ejb-relation | -Optional | -
| foreign-key-jdbc-name | -Optional. - Default value is the abstract-schema-name of the destination bean of - the "one" side of the relationship (i.e. the source bean of the - relationship role with multiplicity one), suffixed by _, and - by its primary-key-field. - B_idb in the example. |
-
..... - <relationships> - <ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <ejb-relationship-role> - <!-- A => B --> - <ejb-relationship-role-name>a2b</ejb-relationship-role-name> - <multiplicity>Many</multiplicity> - <relationship-role-source> - <ejb-name>A</ejb-name> - </relationship-role-source> - <cmr-field> - <cmr-field-name>b</cmr-field-name> - <cmr-field-type>java.util.Collection</cmr-field-type> - </cmr-field> - </ejb-relationship-role> - <ejb-relationship-role> - <!-- B => A --> - <ejb-relationship-role-name>b2a</ejb-relationship-role-name> - <multiplicity>Many</multiplicity> - <relationship-role-source> - <ejb-name>B</ejb-name> - </relationship-role-source> - </ejb-relationship-role> - </ejb-relation> - </relationships> - ..... -- -
-
|
-
-
|
-
-
|
-
In this case, there is a join table composed of the foreign keys of each -entity bean table.
- -..... - <jonas-ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <jdbc-table-name>tJoin_AB</jdbc-table-name> - <jonas-ejb-relationship-role> - <ejb-relationship-role-name>a2b</ejb-relationship-role-name> - <foreign-key-jdbc-mapping> - <foreign-key-jdbc-name>cfk_idb</foreign-key-jdbc-name> - </foreign-key-jdbc-mapping> - </jonas-ejb-relationship-role> - <jonas-ejb-relationship-role> - <ejb-relationship-role-name>b2a</ejb-relationship-role-name> - <foreign-key-jdbc-mapping> - <foreign-key-jdbc-name>cfk_ida</foreign-key-jdbc-name> - </foreign-key-jdbc-mapping> - </jonas-ejb-relationship-role> - </jonas-ejb-relation> - ..... -- -
Default values
- -| jonas-ejb-relation | -Optional | -
| jdbc-table-name | -Optional. - Default value is built from the abstract-schema-names of the beans, - separated by _. - A_B in the example. |
-
| foreign-key-jdbc-name | -Optional. - Default value is the abstract-schema-name of the destination bean, - suffixed by _, and by its primary-key-field. - B_idb and A_ida in the example. |
-
Similar to N-M unidirectional relationships, but a CMR field is defined -for each bean.
- -..... - <relationships> - <ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <ejb-relationship-role> - <!-- A => B --> - <ejb-relationship-role-name>a2b</ejb-relationship-role-name> - <multiplicity>Many</multiplicity> - <relationship-role-source> - <ejb-name>A</ejb-name> - </relationship-role-source> - <cmr-field> - <cmr-field-name>b</cmr-field-name> - <cmr-field-type>java.util.Collection</cmr-field-type> - </cmr-field> - </ejb-relationship-role> - <ejb-relationship-role> - <!-- B => A --> - <ejb-relationship-role-name>b2a</ejb-relationship-role-name> - <multiplicity>Many</multiplicity> - <relationship-role-source> - <ejb-name>B</ejb-name> - </relationship-role-source> - <cmr-field> - <cmr-field-name>a</cmr-field-name> - <cmr-field-type>java.util.Collection</cmr-field-type> - </cmr-field> - </ejb-relationship-role> - </ejb-relation> - </relationships> - ..... -- -
-
|
-
-
|
-
-
|
-
In this case, there is a join table composed of the foreign keys of each -entity bean table.
- -..... - <jonas-ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <jdbc-table-name>tJoin_AB</jdbc-table-name> - <jonas-ejb-relationship-role> - <ejb-relationship-role-name>a2b</ejb-relationship-role-name> - <foreign-key-jdbc-mapping> - <foreign-key-jdbc-name>cfk_idb</foreign-key-jdbc-name> - </foreign-key-jdbc-mapping> - </jonas-ejb-relationship-role> - <jonas-ejb-relationship-role> - <ejb-relationship-role-name>b2a</ejb-relationship-role-name> - <foreign-key-jdbc-mapping> - <foreign-key-jdbc-name>cfk_ida</foreign-key-jdbc-name> - </foreign-key-jdbc-mapping> - </jonas-ejb-relationship-role> - </jonas-ejb-relation> - ..... -- -
Default values:
- -| jonas-ejb-relation | -Optional | -
| jdbc-table-name | -Optional. - Default value is built from the abstract-schema-names of the beans, - separated by _. - A_B in the example. |
-
| foreign-key-jdbc-name | -Optional. - Default value is the abstract-schema-name of the destination bean, - suffixed by _, and by its primary-key-field. - B_idb and A_ida in the example. |
-
In the case of composite primary keys, the database mapping should provide -the capability to specify which column of a foreign key corresponds to which -column of the primary key. This is the only difference between relationships -based on simple primary keys. For this reason, not all types of relationship -are illustrated below.
- -..... - <entity> - <ejb-name>A</ejb-name> - ..... - <prim-key-class>p.PkA</prim-key-class> - ..... - <cmp-field> - <field-name>id1A</field-name> - </cmp-field> - <cmp-field> - <field-name>id2A</field-name> - </cmp-field> - ..... - </entity> - ..... - <entity> - <ejb-name>B</ejb-name> - ..... - <prim-key-class>p.PkB</prim-key-class> - ..... - <cmp-field> - <field-name>id1B</field-name> - </cmp-field> - <cmp-field> - <field-name>id2B</field-name> - </cmp-field> - ..... - </entity> - ..... - <relationships> - <ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <ejb-relationship-role> - <!-- A => B --> - <ejb-relationship-role-name>a2b</ejb-relationship-role-name> - <multiplicity>One</multiplicity> - <relationship-role-source> - <ejb-name>A</ejb-name> - </relationship-role-source> - <cmr-field> - <cmr-field-name>b</cmr-field-name> - </cmr-field> - </ejb-relationship-role> - <ejb-relationship-role> - <!-- B => A --> - <ejb-relationship-role-name>b2a</ejb-relationship-role-name> - <multiplicity>One</multiplicity> - <relationship-role-source> - <ejb-name>B</ejb-name> - </relationship-role-source> - <cmr-field> - <cmr-field-name>a</cmr-field-name> - </cmr-field> - </ejb-relationship-role> - </ejb-relation> - </relationships> - ..... -- -
Two mappings are possible, one or another of the tables may hold the -foreign key.
- -Case 1:
- -
-
|
-
-
|
-
Case 2:
- -
-
|
-
-
|
-
Case 1:
-..... - <jonas-ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <jonas-ejb-relationship-role> - <ejb-relationship-role-name>a2b</ejb-relationship-role-name> - <foreign-key-jdbc-mapping> - <foreign-key-jdbc-name>cfk_id1b</foreign-key-jdbc-name> - <key-jdbc-name>c_id1b</key-jdbc-name> - </foreign-key-jdbc-mapping> - <foreign-key-jdbc-mapping> - <foreign-key-jdbc-name>cfk_id2b</foreign-key-jdbc-name> - <key-jdbc-name>c_id2b</key-jdbc-name> - </foreign-key-jdbc-mapping> - </jonas-ejb-relationship-role> - </jonas-ejb-relation> - ..... -- -
Case 2:
-..... - <jonas-ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <jonas-ejb-relationship-role> - <ejb-relationship-role-name>b2a</ejb-relationship-role-name> - <foreign-key-jdbc-mapping> - <foreign-key-jdbc-name>cfk_id1a</foreign-key-jdbc-name> - <key-jdbc-name>c_id1a</key-jdbc-name> - </foreign-key-jdbc-mapping> - <foreign-key-jdbc-mapping> - <foreign-key-jdbc-name>cfk_id2a</foreign-key-jdbc-name> - <key-jdbc-name>c_id2a</key-jdbc-name> - </foreign-key-jdbc-mapping> - </jonas-ejb-relationship-role> - </jonas-ejb-relation> - ..... -- -
For the default mapping (values), the foreign key is in the table of the -source bean of the first ejb-relationship-role of the ejb-relation. In the -example, the default mapping corresponds to case 1, since the -ejb-relationship-role a2b is the first defined in the ejb-relation a-b.
- - -..... - <entity> - <ejb-name>A</ejb-name> - ..... - <cmp-field> - <field-name>id1A</field-name> - </cmp-field> - <cmp-field> - <field-name>id2A</field-name> - </cmp-field> - ..... - </entity> - ..... - <entity> - <ejb-name>B</ejb-name> - ..... - <cmp-field> - <field-name>id1B</field-name> - </cmp-field> - <cmp-field> - <field-name>id2B</field-name> - </cmp-field> - ..... - </entity> - ..... - <relationships> - <ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <ejb-relationship-role> - <!-- A => B --> - <ejb-relationship-role-name>a2b</ejb-relationship-role-name> - <multiplicity>Many</multiplicity> - <relationship-role-source> - <ejb-name>A</ejb-name> - </relationship-role-source> - <cmr-field> - <cmr-field-name>b</cmr-field-name> - <cmr-field-type>java.util.Collection</cmr-field-type> - </cmr-field> - </ejb-relationship-role> - <ejb-relationship-role> - <!-- B => A --> - <ejb-relationship-role-name>b2a</ejb-relationship-role-name> - <multiplicity>Many</multiplicity> - <relationship-role-source> - <ejb-name>B</ejb-name> - </relationship-role-source> - </ejb-relationship-role> - </ejb-relation> - </relationships> - ..... -- -
-
|
-
-
|
-
-
|
-
In this case, there is a join table composed of the foreign keys of each -entity bean table.
- -..... - <jonas-ejb-relation> - <ejb-relation-name>a-b</ejb-relation-name> - <jdbc-table-name>tJoin_AB</jdbc-table-name> - <jonas-ejb-relationship-role> - <ejb-relationship-role-name>a2b</ejb-relationship-role-name> - <foreign-key-jdbc-mapping> - <foreign-key-jdbc-name>cfk_id1b</foreign-key-jdbc-name> - <key-jdbc-name>c_id1b</key-jdbc-name> - </foreign-key-jdbc-mapping> - <foreign-key-jdbc-mapping> - <foreign-key-jdbc-name>cfk_id2b</foreign-key-jdbc-name> - <key-jdbc-name>c_id2b</key-jdbc-name> - </foreign-key-jdbc-mapping> - </jonas-ejb-relationship-role> - <jonas-ejb-relationship-role> - <ejb-relationship-role-name>b2a</ejb-relationship-role-name> - <foreign-key-jdbc-mapping> - <foreign-key-jdbc-name>cfk_id1a</foreign-key-jdbc-name> - <key-jdbc-name>c_id1a</key-jdbc-name> - </foreign-key-jdbc-mapping> - <foreign-key-jdbc-mapping> - <foreign-key-jdbc-name>cfk_id2a</foreign-key-jdbc-name> - <key-jdbc-name>c_id2a</key-jdbc-name> - </foreign-key-jdbc-mapping> - </jonas-ejb-relationship-role> - </jonas-ejb-relation> - ..... -- - diff --git a/jonas_doc/olddoc/PG_Environment.html b/jonas_doc/olddoc/PG_Environment.html deleted file mode 100644 index 82090226bd56355a3a262490c3a3fdbe06bfb4ae..0000000000000000000000000000000000000000 --- a/jonas_doc/olddoc/PG_Environment.html +++ /dev/null @@ -1,300 +0,0 @@ - - - - - - -
The target audience for this guide is the Enterprise Bean provider, i.e. -the person in charge of developing the software components on the server -side. It describes how an enterprise component can refer to values, -resources, or other components in a way that is configurable at deployment -time.
- -The content of this guide is the following:
-The enterprise bean environment is a mechanism that allows customization -of the enterprise bean's business logic during assembly or deployment. The -environment is a way for a bean to refer to a value, to a resource, or to -another component so that the code will be independent of the actual referred -object. The actual value of such environment references (or variables) is set -at deployment time, according to what is contained in the deployment -descriptor. The enterprise bean's environment allows the enterprise bean to -be customized without the need to access or change the enterprise bean's -source code.
- -The enterprise bean environment is provided by the container (i.e. the -JOnAS server) to the bean through the JNDI interface as a JNDI context. The -bean code accesses the environment using JNDI with names starting with -"java:comp/env/".
- -The bean provider declares all the bean environment entries in the -deployment descriptor via the env-entry element. The deployer can -set or modify the values of the environment entries.
- -A bean accesses its environment entries with a code similar to the -following:
- InitialContext ictx = new InitialContext();
- Context myenv = ictx.lookup("java:comp/env");
- Integer min = (Integer) myenv.lookup("minvalue");
- Integer max = (Integer) myenv.lookup("maxvalue");
-
-
-In the standard deployment descriptor, the declaration of these variables -are as follows:
-<env-entry> - <env-entry-name>minvalue</env-entry-name> - <env-entry-type>java.lang.Integer</env-entry-type> - <env-entry-value>12</env-entry-value> - </env-entry> - <env-entry> - <env-entry-name>maxvalue</env-entry-name> - <env-entry-type>java.lang.Integer</env-entry-type> - <env-entry-value>120</env-entry-value> - </env-entry> -- -
The resource references are another examples of environment entries. For -such entries, using subcontexts is recommended:
-In the standard deployment descriptor, the declaration of a resource -reference to a JDBC connection factory is:
-<resource-ref> - <res-ref-name>jdbc/AccountExplDs</res-ref-name> - <res-type>javax.sql.DataSource</res-type> - <res-auth>Container</res-auth> - </resource-ref> -- -
And the bean accesses the datasource as in the following:
- InitialContext ictx = new InitialContext();
- DataSource ds = ictx.lookup("java:comp/env/jdbc/AccountExplDs");
-
-
-Binding of the resource references to the actual resource manager -connection factories that are configured in the EJB server is done in the -JOnAS-specific deployment descriptor using the jonas-resource -element.
-<jonas-resource> - <res-ref-name>jdbc/AccountExplDs</res-ref-name> - <jndi-name>jdbc_1</jndi-name> - </jonas-resource> -- -
The resource environment references are another example of environment -entries. They allow the Bean Provider to refer to administered objects that -are associated with resources (for example, JMS Destinations), by using -logical names. Resource environment references are defined in the -standard deployment descriptor.
-<resource-env-ref> - <resource-env-ref-name>jms/stockQueue</resource-env-ref-name> - <resource-env-ref-type>javax.jms.Queue</resource-env-ref-type> - </resource-env-ref> --Binding of the resource environment references to administered objects in the -target operational environment is done in the JOnAS-specific deployment -descriptor using the jonas-resource-env element. -
<jonas-resource-env> - <resource-env-ref-name>jms/stockQueue</resource-env-ref-name> - <jndi-name>myQueue<jndi-name> - </jonas-resource-env> -- -
The EJB reference is another special entry in the enterprise bean's -environment. EJB references allow the Bean Provider to refer to the homes of -other enterprise beans using logical names. For such entries, using -the subcontext java:comp/env/ejb is recommended.
- -The declaration of an EJB reference used for accessing the bean through -its remote home and component interfaces in the standard deployment -descriptor is shown in the following example:
-<ejb-ref> - <ejb-ref-name>ejb/ses1</ejb-ref-name> - <ejb-ref-type>session</ejb-ref-type> - <home>tests.SS1Home</home> - <remote>tests.SS1</remote> - </ejb-ref> -- -
The declaration of an EJB reference used for accessing the bean through -its local home and component interfaces in the standard deployment -descriptor is shown in the following example:
-<ejb-local-ref> - <ejb-ref-name>ejb/locses1</ejb-ref-name> - <ejb-ref-type>session</ejb-ref-type> - <local-home>tests.LocalSS1Home</local-home> - <local>tests.LocalSS1</local> - <ejb-link>LocalBean</ejb-link> - </ejb-local-ref> -- -
-Local interfaces are available in the same JVM as the bean providing this interface.
-The use of these interfaces also implies that the classloader of the component performing a lookup
- (bean or servlet component) is a child of the EJB classloader providing the local interface.
- Local interfaces, then, are not available to outside WARs or outside EJB-JARs
- even if they run in the same JVM. This is due to the fact that classes of
- the local interfaces are not visible on the client side.
- Putting them under the WEB-INF/lib folder of a WAR would not change
- anything as the two classes would be loaded by different classloaders,
- which will throw a "ClassCastException".
-
If the referred bean is defined in the same ejb-jar or EAR file, the -optional ejb-link element of the ejb-ref element can -be used to specify the actual referred bean. The value of the ejb-link -element is the name of the target enterprise bean, i.e. the name defined in -the ejb-name element of the target enterprise bean. If the target enterprise -bean is in the same EAR file, but in a different ejb-jar file, the name of -the ejb-link element may be the name of the target bean, prefixed by the -name of the containing ejb-jar file followed by '#' (e.g. -"My_EJBs.jar#bean1"); prefixing by the name of the ejb-jar file is necessary -only if some ejb-name conflicts occur, otherwise the name of the target bean -is enough. In the following example, the ejb-link element has been -added to the ejb-ref (in the referring bean SSA) and a part of the -description of the target bean (SS1) is shown:
-<session> - <ejb-name>SSA</ejb-name> - ... - <ejb-ref> - <ejb-ref-name>ejb/ses1</ejb-ref-name> - <ejb-ref-type>session</ejb-ref-type> - <home>tests.SS1Home</home> - <remote>tests.SS1</remote> - <ejb-link>SS1</ejb-link> - </ejb-ref> - ... - </session> - ... - <session> - <ejb-name>SS1</ejb-name> - <home>tests.SS1Home</home> - <local-home>tests.LocalSS1Home</local-home> - <remote>tests.SS1</remote> - <local>tests.LocalSS1</local> - <ejb-class>tests.SS1Bean</ejb-class> - ... - </session> - ... -- -
If the bean SS1 was not in the same ejb-jar file as SSA, but in another -file named product_ejbs.jar, the ejb-link element could have been:
-<ejb-link>product_ejbs.jar#SS1</ejb-link> -- -
If the referring component and the referred bean are in separate files and -not in the same EAR, the current JOnAS implementation does not allow use of -the ejb-link element. In this case, to resolve the reference, the -jonas-ejb-ref element in the JOnAS-specific deployment descriptor -would be used to bind the environment JNDI name of the EJB reference to the -actual JNDI name of the associated enterprise bean home. In the following -example, it is assumed that the JNDI name of the SS1 bean home is -SS1Home_one.
-<jonas-session> - <ejb-name>SSA</ejb-name> - <jndi-name>SSAHome</jndi-name> - <jonas-ejb-ref> - <ejb-ref-name>ejb/ses1</ejb-ref-name> - <jndi-name>SS1Home_one</jndi-name> - </jonas-ejb-ref> - </jonas-session> - ... - <jonas-session> - <ejb-name>SS1</ejb-name> - <jndi-name>SS1Home_one</jndi-name> - <jndi-local-name>SS1LocalHome_one</jndi-local-name> - </jonas-session> - ... -- -
The bean locates the home interface of the other enterprise bean using the -EJB reference with the following code:
- InitialContext ictx = new InitialContext();
- Context myenv = ictx.lookup("java:comp/env");
- SS1Home home = (SS1Home)javax.rmi.PortableRemoteObject.narrow(myEnv.lookup("ejb/ses1"),
- SS1Home.class);
-
-
-JOnAS provides support for EJB 1.0-style definition of environment -properties. EJB1.0 environment must be declared in the -ejb10-properties sub-context. For example:
-<env-entry> - <env-entry-name>ejb10-properties/foo</env-entry-name> - <env-entry-type>java.lang.String</env-entry-type> - <env-entry-value>foo value</env-entry-value> - </env-entry> -- -
The bean can retrieve its environment with the following code:
- SessionContext ctx;
- Properties prop;
- public void setSessionContext(SessionContext sc) {
- ctx = sc;
- prop = ctx.getEnvironment();
- }
- public mymethod() {
- String foo = prop.getProperty("foo");
- ...
- }
-
-
-
diff --git a/jonas_doc/olddoc/PG_J2eeApps.html b/jonas_doc/olddoc/PG_J2eeApps.html
deleted file mode 100644
index 71ee36f09e94f07c6e0bd01051396f00fc20e5df..0000000000000000000000000000000000000000
--- a/jonas_doc/olddoc/PG_J2eeApps.html
+++ /dev/null
@@ -1,317 +0,0 @@
-
-
-
-
-
-
- The target audience for this guide is the application component provider, -i.e., the person in charge of developing the software components on the server -side (the business tier).
- -The content of this guide is the following:
-JOnAS supports two types of J2EE application components: Enterprise -Beans and Web components. In addition to providing guides for -construction of application components, guides are supplied for application -assembly, deployment, and administration.
- -The individual in charge of developing Enterprise Beans should consult the -Enterprise Beans Programmer's Guide for instructions on how to perform the -following tasks:
-This JOnAS documentation provides guides for developing the three types of -enterprise bean:
- - -Deployment descriptor specification is presented in the Defining the Deployment -Descriptor chapter.
- -More specific issues related to transaction behaviour, the Enterprise Bean -environment, or security service, are presented in the corresponding -chapters: Transactional behaviour, Enterprise Bean -Environment, Security Management.
- -Principles and tools for providing EJB JAR files are presented in the -chapters EJB -Packaging and Deployment -and Installation Guide.
- -Web designers in charge of JSP pages and software developers providing -servlets can consult the Web Application Programmer's Guide.
- -The Developing Web -Components guide explains how to construct Web components, as well as how -to access Enterprise Beans from within the Web Components.
-Deployment descriptor specification is presented in the Defining the Web -Deployment Descriptor chapter. - -Web components can be used as Web application components or as
-J2EE application components. In both cases, a WAR file will be
-created, but the content of this file is different in the two situations. In
-the first case, the WAR contains the Web components and the Enterprise Beans.
-In the second case, the WAR does not contain the Enterprise Beans. The EJB
-JAR file containing the Enterprise Beans is packed together with the WAR file
-containing the Web components, into an EAR file.
-Principles and tools for providing WAR files are presented in WAR Packaging and
-the Deployment and
-Installation Guide.
The application assembler in charge of assembling the application -components already bundled in EJB JAR files and WAR files into a J2EE EAR -file, can obtain useful information from the J2EE Application -Assembler's Guide chapter.
- -JOnAS provides tools for the deployment and administration of Enterprise -Beans (EJB JARs), Web applications (WARs), and J2EE applications (EARs).
- -The Deployment and -Installation Guide covers issues related to the deployment of application -components.
- -The Administration Guide -presents information about how to manage the JOnAS server and the JOnAS -services that allow deployment of the different types of application -components: EJB Container service, Web Container service, and EAR service.
- -This section describes a new and important key feature of the J2EE -integration: the class loader hierarchy in JOnAS.
- -An application is deployed by its own class loader. This means, for
-example, that if a WAR and an EJB JAR are deployed separately, the classes
-contained in the two archives are loaded with two separate classloaders with
-no hierarchy between them. Thus, the EJBs from within the JAR will not be
-visible to the Web components in the WAR.
-This is not acceptable in cases where the Web components of an application
-need to reference and use some of the EJBs (this concerns local references in
-the same JVM).
For this reason, prior to EAR files, when a Web application had to be -deployed using EJBs, the EJB JAR had to be located in the -WEB-INF/lib directory of the Web application.
- -Currently, with the J2EE integration and the use of the EAR packaging, -class visibility problems no longer exist and the EJB JAR is no longer -required in the WEB-INF/lib directory.
- -The following sections describe the JOnAS class loader hierarchy and -explain the mechanism used to locate the referenced classes.
- -The commons class loader is a JOnAS-specific class loader that will load
-all classes required to start the JOnAS server. This class loader has the
-system class loader as parent class loader. The commons class loader adds all
-the common libraries required to start the JOnAS server (J2EE apps, commons
-logging, objectweb components, etc.); it also loads the classes located in
-XTRA_CLASSPATH.
The JARs loaded by the commons class loader are located
-under the JONAS_ROOT/lib/commons and JONAS_BASE/lib/commons directories. You can
-extend this class loader by adding your own JARs inside these
-directories. If you are using a Jetty packaging,
-JONAS_ROOT/lib/jetty will be loaded too.
-
Note that the lib/ext extension mechanism is now
- deprecated. You should place additional JARs directly in the
- classloader directory (commons, apps,
- tools) under JONAS_ROOT and/or JONAS_BASE.
- You should now use the JONAS_BASE/lib/commons if you want to
- extend the commons ClassLoader, JONAS_BASE/lib/apps
- for apps ClassLoader and JONAS_BASE/lib/tools
- for tools ClassLoader.
- Notice that the JONAS_BASE extension directories are always
- loaded after JONAS_ROOT directories, so if the same class is in JONAS_ROOT/lib/commons
- and in JONAS_BASE/lib/commons, the one located in JONAS_ROOT/lib/commons will be used.
-
-
To have a library available for each component running inside JOnAS, add
-the required JAR files in the JONAS_ROOT/lib/commons directory or in
-the JONAS_BASE/lib/commons. All jars in subordinate directories will
-also be loaded.
-If a specific jar is needed only for a web application (i.e., need to use a
-version of a jar file which is different than a version loaded by JOnAS),
-change the compliance of the web application classloader to the java 2
-delegation model. Refer to the following: WEB class loader.
-It is also possible to use the extension mechanism, which is described in the
-section dependencies of the J2EE specification (section 8.1.1.28).
The application class loader is a JOnAS-specific class loader that will
-load all application classes required by the user applications. This implies
-that this loader will load all single RAR files. Thus, all applications
-have the visibility of the resource adapters classes. This class loader has the
-commons class loader as parent class loader.
The JARs loaded by the application class loader are
- located under the JONAS_ROOT/lib/apps directory,
- under JONAS_ROOT/lib/catalina/common/lib directory
- (CATALINA_HOME/common/lib if you are not using the
- Tomcat package) and under JONAS_BASE/lib/apps directory.
- You can extend this class loader by adding your own
- JARs inside these directories.
-
The tools class loader is a JOnAS-specific class loader that will load all
-classes for which applications do not require visibility. (User applications
-will not have the ability to load the classes packaged in the tools class
-loader). For example, it includes the jakarta velocity and digester
-components. This class loader has the commons class loader as parent class
-loader.
The JARs loaded by the tools class loader are located under the
- JONAS_ROOT/lib/tools directory and under the
- JONAS_BASE/lib/tools directory. You can extend this class loader
- by adding your own JARs inside these directories.
-
The tomcat class loader is a class loader that will load all classes of
-the tomcat server (CATALINA_HOME/server/lib directory). The
-classes of the common directory of tomcat
-(CATALINA_HOME/common/lib directory) are loaded by the
-application classloader and not by this tomcat classloader. Applications have
-the visibility of the classes and not the server classes. To have
-the visibility of the server classes, the context must have
-the privileged attribute set to true. This class loader
-has the application class loader as parent class loader.
The JARs loaded by the tomcat class loader are located
- under the JONAS_ROOT/lib/catalina/server/lib directory (if
- using Tomcat packaging, unless these libs are located under
- CATALINA_HOME/server/lib). You can extend this class
- loader by adding your own JARs inside this directory.
-
The JOnAS class loader hierarchy that allows the deployment of EAR -applications without placing the EJB JAR in the WEB-INF/lib -directory consists of the following:
- -The EAR class loader is responsible for loading the EAR application. There -is only one EAR class loader per EAR application. This class loader is the -child of the application class loader, thus making JOnAS classes visible to -it.
- -The EJB class loader is responsible for loading all the EJB JARs of the -EAR application, thus all the EJBs of the same EAR application are loaded -with the same EJB classloader. This class loader is the child of the EAR -class loader.
- -The WEB class loader is responsible for loading the Web components. There -is one WEB class loader per WAR file, and this class loader is the child of -the EJB class loader. Using this class loader hierarchy (the EJB class loader -is the parent of the WEB class loader) eliminates the problem of visibility -between classes when a WEB component tries to reference EJBs; the classes -loaded with the EJB class loader are definitely visible to the classes loaded -by its child class loader (WEB class loader).
- -The compliance of the class loader of the web application to the java 2 -delegation model can be changed by using the jonas-web.xml file. This is -described in the section "Defining the Web Deployment -Descriptor."
- -If the java2-delegation-model element is set to false, the class loader of -the web application looks for the class in its own repository before asking -its parent class loader.
- -The resulting JOnAS class loader hierarchy is as follows:
- -
As required by the J2EE v1.4 specification, application components -(servlets, JSP pages and enterprise beans) can use JMS for Java messaging. -Furthermore, applications can use Message-driven Beans for asynchronous EJB -method invocation, as specified by the EJB 2.1 specification.
- -Starting with the JOnAS 3.1 version, JOnAS supports the Java Message -Service Specification 1.1. Previously in JMS 1.0.2, client programming for -Point-to-point and Pub/Sub domains was achieved using similar, but separate, -class hierarchies. Now, JMS 1.1 offers a domain-independent approach to -programming the client application. Thus, the programming model is simpler -and it is now possible to engage queues and topics in the same -transaction.
- -Enterprise Bean providers can use JMS Connection Factory resources via -resource references, and JMS Destination resources (JMS Queues and JMS -Topics) via resource environment references. Thus, they are able to -provide JMS code, inside an EJB method or web component method, for sending -or synchronously receiving messages to/from a JMS Queue or Topic.
- -The EJB container and the Web container can allow for JMS operations -within a global transaction, which may include other resources such as -databases.
- -JOnAS integrates a third party JMS implementation (JORAM) which is the default JMS -service, and for which a J2EE1.4-compliant Resource Adapter archive file is -also provided. Other JMS providers, such as SwiftMQ and WebSphere MQ, -may easily be integrated.
- -Starting with release 4.1, a JMS provider can be integrated within JOnAS -by deploying a corresponding resource adapter. This is the -preferred method as the JMS service will eventually become deprecated in -later JOnAS releases. Also, this method allows deployment of 2.1 MDBs (not -possible with the JMS service).
- -For performing JMS operations, JMS-administered objects will be used by -the application components, such as connection factories and destinations. -Refer to the JMS Administration section for -an explanation of how to create those objects.
- -Additionally, the SwiftMQ product -and IBM's WebSphere MQ -have been used with JOnAS.
- -Refer to the JOnAS example jms as a supplement to this
-present reading. This example jms is described here.
javax.jms.ConnectionFactory,
- javax.jms.QueueConnectionFactory and
- javax.jms.TopicConnectionFactory) are connection factories
- for JMS connection objects.javax.mail.Session or
- javax.mail.internet.MimePartDataSource) are connection
- factories for Java Mail connection objects.Note that starting with JMS 1.1, it is recommended that only the
-javax.jms.ConnectionFactory be used (rather than
-javax.jms.QueueConnectionFactory or
-javax.jms.TopicConnectionFactory ). However, the new
-implementation is fully backwards compatible and existing applications will
-work as is.
The standard deployment descriptor should contain the following
-resource-ref element:
<resource-ref> - <res-ref-name>jms/conFact</res-ref-name> - <res-type>javax.jms.ConnectionFactory</res-type> - <res-auth>Container</res-auth> - </resource-ref>-This means that the programmer will have access to a -
ConnectionFactory object using the JNDI name
-java:comp/env/jms/conFact. The source code for obtaining the factory
-object is the following:
- ConnectionFactory qcf = (ConnectionFactory)
- ctx.lookup("java:comp/env/jms/conFact");
-The mapping to the actual JNDI name of the connection factory (as assigned by
-the JMS provider administration tool), CF in the example, is defined
-in the JOnAS-specific deployment descriptor with the following element:
-<jonas-resource> - <res-ref-name>jms/conFact</res-ref-name> - <jndi-name>CF</jndi-name> - </jonas-resource>- -
<resource-env-ref> - <resource-env-ref-name>jms/stockQueue</resource-env-ref-name> - <resource-env-ref-type>javax.jms.Queue<resource-env-ref-type> - </resource-env-ref>-The application component's source code should contain: -
Queue q = (Queue) ctx.lookup("java:comp/env/jms/stockQueue");
-the mapping to the actual JNDI name (e.g. "myQueue") being defined in the
-JOnAS-specific deployment descriptor in the following way:
-<jonas-resource-env> - <resource-env-ref-name>jms/stockQueue</resource-env-ref-name> - <jndi-name>myQueue<jndi-name> - </jonas-resource-env>- -
void sendMyMessage() {
-
- ConnectionFactory cf = (ConnectionFactory)
- ctx.lookup("java:comp/env/jms/conFact");
- Queue queue = (Queue) ctx.lookup("java:comp/env/jms/stockQueue");
- Connection conn = cf.createConnection();
- Session sess = conn.createSession(true, Session.AUTO_ACKNOWLEDGE);
-
-
-
- MessageProducer mp = sess.createProducer((Destination)queue);
- ObjectMessage msg = sess.createObjectMessage();
- msg.setObject("Hello");
- sender.send(msg);
- sess.close();
- conn.close();
- }
-It is also possible for an application component to synchronously
-receive a message. An EJB method performing synchronous message reception on
-a queue is illustrated in the following:
- public String recMsg() {
- ConnectionFactory cf = (ConnectionFactory)
- ctx.lookup("java:comp/env/jms/conFact");
- Queue queue = (Queue) ctx.lookup("java:comp/env/jms/stockQueue");
- Connection conn = cf.createConnection();
- Session sess = conn.createSession(true, Session.AUTO_ACKNOWLEDGE);
- MessageConsumer mc = sess.createConsumer((Destination)queue);
- conn.start();
- ObjectMessage msg = (ObjectMessage) mc.receive();
- String msgtxt = (String) msg.getObject();
- sess.close();
- conn.close();
- return msgtxt;
- }
-A method that performs JMS operations should always contain the session
-create and close statements, as follows:
- public void doSomethingWithJMS (...) {
- ...
- session = connection.createSession(...);
- ... // JMS operations
- session.close();
- }
-The contained JMS operations will be a part of the transaction, if there is
-one, when the JOnAS server executes the method.
-
-Be sure to never send and receive a particular message in the same -transaction, since the JMS sending operations are actually performed at -commit time only.
- -The previous examples illustrate point-to-point messaging. However,
-application components can also be developed using the publish/subscribe JMS
-API, i.e. using the Topic instead of the Queue
-destination type. This offers the capability of broadcasting a message to
-several message consumers at the same time. The following example illustrates
-a typical method for publishing a message on a JMS topic and demonstrates how
-interfaces have been simplified since JMS 1.1.
public void sendMsg(java.lang.String s) {
- ConnectionFactory cf = (ConnectionFactory)
- ictx.lookup("java:comp/env/jms/conFactSender");
- Topic topic = (Topic) ictx.lookup("java:comp/env/jms/topiclistener");
- Connection conn = cf.createConnection();
- Session session = conn.createSession(true, Session.AUTO_ACKNOWLEDGE);
- MessageConsumer mc = session.createConsumer((Destination)topic);
- ObjectMessage message = session.createObjectMessage();
- message.setObject(s);
- mc.send(message);
- session.close();
- conn.close();
- }
-
-public class EjbCompBean implements SessionBean {
- ...
- QueueConnectionFactory qcf = null;
- Queue queue = null;
-
- public void ejbCreate() {
- ....
- ictx = new InitialContext();
- qcf = (QueueConnectionFactory)
- ictx.lookup("java:comp/env/jms/conFactSender");
- queue = (Queue) ictx.lookup("java:comp/env/jms/queue1");
- }
-
- public void doSomethingWithJMS (...) {
- ...
- Connection conn = qcf.createConnection();
- Session session = conn.createSession(...);
- ... // JMS operations
- session.close();
- conn.close();
- }
-
- ...
-}
-To keep the connection open during the life of a bean instance, the
-programming style shown in the following example is preferred, since it
-avoids many connection opening and closing operations:
-public class EjbCompBean implements SessionBean {
- ...
- ConnectionFactory qcf = null;
- Queue queue = null;
- Connection conn = null;
-
- public void ejbCreate() {
- ....
- ictx = new InitialContext();
- cf = (ConnectionFactory)
- ictx.lookup("java:comp/env/jms/conFactSender");
- queue = (Queue) ictx.lookup("queue1");
- conn = cf.createConnection();
- }
-
- public void doSomethingWithJMS (...) {
- ...
- Session session = conn.createSession(...);
- ... // JMS operations
- session.close();
- }
-
- public void ejbRemove() {
- conn.close();
- }
-
- ...
-}
-Be aware that maintaining JMS objects in the bean state is not always
-possible, depending on the type of bean.
-Note that, due to a known problem with the Sun JDK 1.3 on Linux, the close -of the connection can block. The problem is fixed with JDK 1.4.
- -public class EjbCompBean implements SessionBean {
- ...
-
- public void doSomethingWithJMS (...) {
- ...
- Connection conn = cf.createConnection();
- Session session = conn.createSession(...);
- ut = ejbContext.getUserTransaction();
- ut.begin();
- ... // JMS operations
- ut.commit();
- session.close();
- conn.close();
- }
-
- ...
-}
-To have the session operations involved in the transaction, the session
-creation and close should be inside the transaction boundaries, and the
-connection creation and close operations can either be both outside the
-transaction boundaries or both inside the transaction boundaries, as follows:
-public class EjbCompBean implements SessionBean {
- ...
-
- public void doSomethingWithJMS (...) {
- ...
- Connection conn = qcf.createConnection();
- ut = ejbContext.getUserTransaction();
- ut.begin();
- Session session = conn.createSession(...);
- ... // JMS operations
- session.close();
- ut.commit();
- conn.close();
- }
-
- ...
-}
-or
-public class EjbCompBean implements SessionBean {
- ...
-
- public void doSomethingWithJMS (...) {
- ...
- ut = ejbContext.getUserTransaction();
- ut.begin();
- Connection conn = cf.createConnection();
- Session session = conn.createSession(...);
- ... // JMS operations
- session.close();
- conn.close();
- ut.commit();
- }
-
- ...
-}
-Programming EJB components with bean-managed transactions can result in
-complex code. Using container-managed transactions can help avoid problems
-such as those previously described.
-
-As provided, the default JMS service and JORAM adapter configurations -automatically create six connection factories and two destination objects.
- -The six connection factories automatically created are described in the -following table:
- - -| JNDI name | -JMS type | -Usage | -
| CF | -ConnectionFactory | -To be used by an application component to create a Connection. | -
| QCF | -QueueConnectionFactory | -To be used by an application component to create a - QueueConnection. | -
| TCF | -TopicConnectionFactory | -To be used by an application component to create a - TopicConnection. | -
| JCF | -ConnectionFactory | -To be used by any other Java component (for instance a client) to - create a Connection. | -
| JQCF | -QueueConnectionFactory | -To be used by any other Java component (for instance a client) to - create a QueueConnection. | -
| JTCF | -TopicConnectionFactory | -To be used by any other Java component (for instance a client) to - create a TopicConnection. | -
The CF, QCF and TCF connection factories are managed connection
-factories. The application components should use only managed connection
-factories to allow JOnAS to manage the JMS resources created via these
-connection factories (the JMS sessions).
-In contrast, JCF, JQCF and JTCF are non-managed connection factories.
-They are used by Java components implementing a JMS client behavior, but
-running outside the application server.
The two destinations automatically created are described in the following -table:
- -| JNDI name | -JMS type | -Usage | -
| sampleQueue | -Queue | -Can be equally used by an EJB component or a Java component. | -
| sampleTopic | -Topic | -Can be equally used by an EJB component or a Java component. | -
jonas.services security,jtm,dbm,jms,ejb- -
JOnAS will not create additional connection factories when using the -default configuration. However, JOnAS can create requested destination -objects at server launching time, if specified in the jonas.properties -file. To do this, specify the JNDI names of the Topic and Queue destination -objects to be created in a jonas.service.jms.topics and -jonas.service.jms.queues property respectively, as follows:
-jonas.service.jms.topics t1,t2 // JOnAS server creates 2 topic destinations (t1,t2) - jonas.service.jms.queues myQueue // JOnAS server creates 1 queue destination (myQueue)-It is recommended that programmers use resource references and -resource environment references to access the connection factories and -destination objects created by JOnAS, as already presented in the "Writing JMS operations within an application -component" section. - -
Starting with JOnAS release 4.1, it is recommended that a JMS resource -adapter be deployed instead of using the jms service. Refer to the -JMS Resource Adapters configuration -guide for an explanation.
- -jonas start- -
The Message-Oriented Middleware (the JMS provider implementation) is -automatically started (or at least accessed) and the JMS-administered objects -that will be used by the Enterprise Beans are automatically created and -registered in JNDI.
- -Then, the EJB can be deployed as usual with:
-jonas admin -a XX.jar- -
For launching the MOM, consider the following possibilities:
-$JONAS_ROOT/conf
- directory).
- jonas.service.jms.collocated true- In this case, the MOM will be launched automatically at server launching - time (command jonas start). - -
For other MOMs, use the proprietary command.
-
- In this case, the JOnAS property jonas.service.jms.collocated must
- be set to false in the jonas.properties file.
jonas.service.jms.collocated false-
jonas.service.jms.collocated false - jonas.service.jms.url joram://host2:16010-
Note: the MOM may be directly launched by the proprietary
- command. The command for JORAM is:
- java -DTransaction=fr.dyade.aaa.util.NullTransaction
- fr.dyade.aaa.agent.AgentServer 0 ./s0
This command corresponds to the default options used by the - JmsServer command.
-The server is not persistent when launched with this command. If - persistence is required, the - -DTransaction=fr.dyade.aaa.util.NullTransaction option should be - replaced with the -DTransaction=fr.dyade.aaa.util.NTransaction - option.
-To change other MOM configurations (distribution, multi-servers, ...), - refer to the JORAM documentation on http://joram.objectweb.org.
-Starting with JOnAS release 4.1, a JMS server can be accessed through a -resource adapter which may be deployed.
- -For deploying such a resource adapter, place the corresponding archive
-file (*.rar) in the JOnAS's rars/autoload
-directory, or declare it at the end of the jonas.properties
-file, or deploy it manually through the jonasAdmin tool.
Configuring and deploying such adapters is explained in the Configuring JMS Resource Adapters -section.
- -public class EjbCompBean implements SessionBean {
- ...
- ConnectionFactory cf = null;
- Topic topic = null;
-
- public void ejbCreate() {
- ....
- ictx = new InitialContext();
- cf = (ConnectionFactory)
- ictx.lookup("java:comp/env/jms/conFactSender");
- topic = (Topic) ictx.lookup("java:comp/env/jms/topiclistener");
- }
- ...
-}
-This code has been intentionally cleared from all the elements in which it is
-not necessary for understanding the JMS logic aspects of the example, e.g.
-exception management.
-
-The JMS-administered objects ConnectionFactory and Topic
-have been made available to the bean by a resource reference in the
-first example, and by a resource environment reference in the second
-example.
-The standard deployment descriptor should contain the following element:
<resource-ref> - <res-ref-name>jms/conFactSender</res-ref-name> - <res-type>javax.jms.ConnectionFactory</res-type> - <res-auth>Container</res-auth> - </resource-ref>-
<resource-env-ref> - <resource-env-ref-name>jms/topiclistener</resource-env-ref-name> - <resource-env-ref-type>javax.jms.Topic</resource-env-ref-type> - </resource-env-ref>-The JOnAS-specific deployment descriptor should contain the following element: -
<jonas-resource> - <res-ref-name>jms/conFactSender</res-ref-name> - <jndi-name>TCF</jndi-name> - </jonas-resource>-
<jonas-resource-env> - <resource-env-ref-name>jms/topiclistener</resource-env-ref-name> - <jndi-name>sampleTopic</jndi-name> - </jonas-resource-env>-Note that the EjbComp SessionBean will use the administered objects -automatically created by JOnAS in the default JMS configuration. - -
Because the administered objects are now accessible, it is possible to -perform JMS operations within a method. The following occurs in the -sendMsg method:
-public class EjbCompBean implements SessionBean {
- ...
- public void sendMsg(java.lang.String s) {
- // create Connection, Session and MessageProducer
- Connection conn = null;
- Session session = null;
- MessageProducer mp = null;
- try {
- conn = cf.createConnection();
- session = conn.createSession(true, Session.AUTO_ACKNOWLEDGE);
- mp = session.createProducer((Destination)topic);
- }
- catch (Exception e) {e.printStackTrace();}
-
- // send the message to the topic
- try {
- ObjectMessage message;
- message = session.createObjectMessage();
- message.setObject(s);
- mp.send(message);
- session.close();
- conn.close();
- } catch (Exception e) {
- e.printStackTrace();
- }
- }
- ...
-}
-This method sends a message containing its String argument.
-
-public class EjbCompClient {
- ...
- public static void main(String[] arg) {
- ...
- utx = (UserTransaction) initialContext.lookup("javax.transaction.UserTransaction");
- ...
- home1 = (EjbCompHome) initialContext.lookup("EjbCompHome");
- home2 = (AccountHome) initialContext.lookup("AccountImplHome");
- ...
- EjbComp aJmsBean = home1.create();
- Account aDataBean = null;
- ...
- utx.begin();
- aJmsBean.sendMsg("Hello commit"); // sending a JMS message
- aDataBean = home2.create(222, "JMS Sample OK", 0);
- utx.commit();
-
- utx.begin();
- aJmsBean.sendMsg("Hello rollback"); // sending a JMS message
- aDataBean = home2.create(223, "JMS Sample KO", 0);
- utx.rollback();
- ...
- }
-}
-The result of this client execution will be that:
-public class MsgReceptor {
-
- static Context ictx = null;
- static ConnectionFactory cf = null;
- static Topic topic = null;
-
- public static void main(String[] arg) {
-
- ictx = new InitialContext();
- cf = (ConnectionFactory) ictx.lookup("JCF");
- topic = (Topic) ictx.lookup("sampleTopic");
- ...
- Connection conn = cf.createConnection();
- Session session =
- conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
- MessageConsumer mc = session.createConsumer((Destination)topic);
-
- MyListenerSimple listener = new MyListenerSimple();
- mc.setMessageListener(listener);
- conn.start();
-
- System.in.read(); // waiting for messages
-
- session.close();
- conn.close();
- ...
- }
-}
-public MyListenerSimple implements javax.jms.MessageListener {
- MyListenerSimple() {}
-
- public void onMessage(javax.jms.Message msg) {
- try {
- if(msg==null)
- System.out.println("Message: message null ");
- else {
- if(msg instanceof ObjectMessage) {
- String m = (String) ((ObjectMessage)msg).getObject();
- System.out.println ("JMS client: received message ======> " + m);
- } else if(msg instanceof TextMessage) {
- String m = ((TextMessage)msg).getText();
- System.out.println ("JMS client: received message ======> " + m);
- }
- }catch(Exception exc) {
- System.out.println("Exception caught :" + exc);
- exc.printStackTrace();
- }
- }
-}
-
-
diff --git a/jonas_doc/olddoc/PG_LogModules.html b/jonas_doc/olddoc/PG_LogModules.html
deleted file mode 100644
index 132d2640a34ea3899a95731d52df5ef04dbc7123..0000000000000000000000000000000000000000
--- a/jonas_doc/olddoc/PG_LogModules.html
+++ /dev/null
@@ -1,97 +0,0 @@
-
-
-
-
-
- The content of this guide is the following:
- - - -The login modules for use by clients are defined in the file
-$JONAS_ROOT/conf/jaas.config. Example:
jaasclient {
- // Login Module to use for the example jaasclient.
-
- //First, use a LoginModule for the authentication
- // Use the resource memrlm_1
- org.objectweb.jonas.security.auth.spi.JResourceLoginModule required
- resourceName="memrlm_1"
- ;
-
- // Use the login module to propagate security to the JOnAS server
- // globalCtx is set to true in order to set the security context
- // for all the threads of the client container instead of only
- // on the current thread.
- // Useful with multithread applications (like Swing Clients)
- org.objectweb.jonas.security.auth.spi.ClientLoginModule required
- globalCtx="true"
- ;
-};
-
-
-This file is used when a java client is launched with
-jclient, as a result of the following property being set by
-jclient:
--Djava.security.auth.login.config==$JONAS_ROOT/conf/jaas.config
-
-For more information about the JAAS authentication, refer to the
-JAAS
-authentication tutorial.
CallbackHandler handler1 = new LoginCallbackHandler();
- CallbackHandler handler2 = new DialogCallbackHandler();
- CallbackHandler handler3 = new NoInputCallbackHandler("jonas_user", "jonas_password");
-
- JONAS_ROOT/conf/jaas.config file is called. LoginContext loginContext = new LoginContext("jaasclient", handler2);
-
- loginContext.login(); -- If there are no exceptions, the authentication is successful.
The content of this guide is the following:
-The EJB 2.1 specification defines a new kind of EJB component for -receiving asynchronous messages. This implements some type of "asynchronous -EJB component method invocation" mechanism. The Message-driven Bean (also -referred to as MDB in the following) is an Enterprise JavaBean, not an Entity -Bean or a Session Bean, which plays the role of a JMS MessageListener.
- -The EJB 2.1 specification contains detailed information about MDB. The Java -Message Service Specification 1.1 contains detailed information about JMS. -This chapter focuses on the use of Message-driven beans within the JOnAS -server.
- -JMS messages do not carry any context, thus the onMessage method -will execute without pre-existing transactional context. However, a new -transaction can be initiated at this moment (refer to the "Transactional aspects" section for more -details). The onMessage method can call other methods on the MDB -itself or on other beans, and can involve other resources by accessing -databases or by sending messages. Such resources are accessed the same way as -for other beans (entity or session), i.e., through resource references -declared in the deployment descriptor.
- -The JOnAS container maintains a pool of MDB instances, allowing large -volumes of messages to be processed concurrently. An MDB is similar in some -ways to a stateless session bean: its instances are relatively short-lived, -it retains no state for a specific client, and several instances may be -running at the same time.
- -The MDB class must implement the javax.jms.MessageListener and the -javax.ejb.MessageDrivenBean interfaces. In addition to the -onMessage method, the following must be implemented:
-The following is an example of an MDB class:
-public class MdbBean implements MessageDrivenBean, MessageListener {
-
- private transient MessageDrivenContext mdbContext;
-
- public MdbBean() {}
-
- public void setMessageDrivenContext(MessageDrivenContext ctx) {
- mdbContext = ctx;
- }
-
- public void ejbRemove() {}
-
- public void ejbCreate() {}
-
- public void onMessage(Message message) {
- try {
- TextMessage mess = (TextMessage)message;
- System.out.println( "Message received: "+mess.getText());
- }catch(JMSException ex){
- System.err.println("Exception caught: "+ex);
- }
- }
-}
-
-
-The destination associated to an MDB is specified in the deployment -descriptor of the bean. A destination is a JMS-administered object, -accessible via JNDI. The description of an MDB in the EJB 2.0 deployment -descriptor contains the following elements, which are specific to MDBs:
-The following example illustrates such a deployment descriptor:
-<enterprise-beans> - <message-driven> - <description>Describe here the message driven bean Mdb</description> - <display-name>Message Driven Bean Mdb</display-name> - <ejb-name>Mdb</ejb-name> - <ejb-class>samplemdb.MdbBean</ejb-class> - <transaction-type>Container</transaction-type> - <message-selector>Weight >= 60.00 AND LName LIKE 'Sm_th'</message-selector> - <message-driven-destination> - <destination-type>javax.jms.Topic</destination-type> - <subscription-durability>NonDurable</subscription-durability> - </message-driven-destination> - <acknowledge-mode>Auto-acknowledge</acknowledge-mode> - </message-driven> - </enterprise-beans> -- -
If the transaction type is "container," the transactional behavior of the -MDB's methods are defined as for other enterprise beans in the deployment -descriptor, as in the following example:
-<assembly-descriptor> - <container-transaction> - <method> - <ejb-name>Mdb</ejb-name> - <method-name>*</method-name> - </method> - <trans-attribute>Required</trans-attribute> - </container-transaction> - </assembly-descriptor> -- -
For the onMessage method, only the Required or -NotSupported transaction attributes must be used, since there can be -no pre-existing transaction context.
- -For the message selector specified in the previous example, the sent JMS -messages are expected to have two properties, "Weight" and "LName," for -example assigned in the JMS client program sending the messages, as -follows:
- message.setDoubleProperty("Weight",75.5);
- message.setStringProperty("LName","Smith");
-
-
-Such a message will be received by the Message-driven bean. The message -selector syntax is based on a subset of the SQL92. Only messages whose -headers and properties match the selector are delivered. Refer to the JMS -specification for more details.
- -The JNDI name of a destination associated with an MDB is defined in the -JOnAS-specific deployment descriptor, within a jonas-message-driven -element, as illustrated in the following:
-<jonas-message-driven> - <ejb-name>Mdb</ejb-name> - <jonas-message-driven-destination> - <jndi-name>sampleTopic</jndi-name> - </jonas-message-driven-destination> - </jonas-message-driven> -- -
Once the destination is established, a client application can send -messages to the MDB through a destination object obtained via JNDI as -follows:
- -Queue q = context.lookup("sampleTopic");
If the client sending messages to the MDB is an EJB component itself, it -is preferable that it use a resource environment reference to obtain the -destination object. The use of resource environment references is described -in the JMS -User's Guide (Writing JMS operations within an application component / -Accessing the destination object section).
- -The default policy is that the MDB developer and deployer are not -concerned with JMS administration. This means that the developer/deployer -will not create or use any JMS Connection factories and will not create a JMS -destination (which is necessary for performing JMS operations within an EJB -component, refer to the JMS User's Guide); they will simply define the type of -destination in the deployment descriptor and identify its JNDI name in the -JOnAS-specific deployment descriptor, as described in the previous section. -This means that JOnAS will implicitly create the necessary administered -objects by using the proprietary administration APIs of the JMS -implementation (since the administration APIs are not standardized). To -perform such administration operations, JOnAS uses wrappers to the JMS -provider administration API. For Joram, the wrapper is -org.objectweb.jonas_jms.JmsAdminForJoram (which is the default wrapper -class defined by the jonas.service.jms.mom property in the -jonas.properties file). For SwiftMQ, a -com.swiftmq.appserver.jonas.JmsAdminForSwiftMQ class can be obtained -from the SwiftMQ site.
- -For the purpose of this implicit administration phase, the deployer must -add the 'jms' service in the list of the JOnAS services. For the example -provided, the jonas.properties file should contain the following:
--jonas.services registry,security,jtm,dbm,jms,ejb // The jms service must be added -jonas.service.ejb.descriptors samplemdb.jar -jonas.service.jms.topics sampleTopic // not mandatory- -
The destination objects may or may not pre-exist. The EJB server will not
-create the corresponding JMS destination object if it already exists. (Refer
-also to JMS
-administration). The sampleTopic should be explicitly
-declared only if the JOnAS Server is going to create it first, even if the
-Message-driven bean is not loaded, or if it is used by another client before
-the Message-driven bean is loaded. In general, it is not necessary to declare
-the sampleTopic.
JOnAS uses a pool of threads for executing Message-driven -bean instances on message reception, thus allowing large volumes of messages -to be processed concurrently. As previously explained, MDB instances are -stateless and several instances may execute concurrently on behalf of the -same MDB. The default size of the pool of thread is 10, and it may be -customized via the jonas property -jonas.service.ejb.mdbthreadpoolsize, which is specified in -the jonas.properties file as in the following example:
-jonas.service.ejb.mdbthreadpoolsize 50 -- -
To deploy and run a Message-driven Bean, perform the following steps:
-Start the Message-Oriented Middleware (the JMS provider - implementation). Refer to the section "Launching the Message-Oriented - Middleware."
-Create and register in JNDI the JMS destination object that will be - used by the MDB.
-This can be done automatically by the JMS service or explicitly by the - proprietary administration facilities of the JMS provider (JMS - administration). The JMS service creates the destination object if - this destination is declared in the jonas.properties - file (as specified in the previous section).
-Deploy the MDB component in JOnAS.
-Note that, if the destination object is not already created when - deploying an MDB, the container asks the JMS service to create it based - on the deployment descriptor content.
-When using JMS, it is very important to stop JOnAS using the - jonas stop command; it should not be stopped directly by - killing it.
-If the configuration property jonas.services contains the -jms service, then the JOnAS JMS service will be launched and may try to -launch a JMS implementation (a MOM).
- -For launching the MOM, three possibilities can be considered:
-This is the default situation obtained by assigning the
- true value to the configuration property
- jonas.service.jms.collocated in the
- jonas.properties file.
-jonas.services security,jtm,dbm,jms,ejb // The jms service must be in the list -jonas.service.jms.collocated true-
In this case, the MOM is automatically launched by the JOnAS JMS
- service at the JOnAS launching time (command jonas
- start).
The Joram MOM can be launched using the command:
-JmsServer
For other MOMs, the proprietary command should be used.
-The configuration property
- jonas.service.jms.collocated must be set to
- false in the jonas.properties file. Setting
- this property is sufficient if the JORAM's JVM runs on the same host as
- JONAS, and if the MOM is launched with its default options (unchanged
- a3servers.xml configuration file under JONAS_BASE/conf
- or JONAS_ROOT/conf if JONAS_BASE not defined).
-jonas.services security,jtm,dbm,jms,ejb // The jms service must be in the list -jonas.service.jms.collocated false-
To use a specific configuration for the MOM, such as changing the - default host (which is localhost) or the default connection port number - (which is 16010), requires defining the additional - jonas.service.jms.url configuration property as - presented in the following case.
-This requires defining the jonas.service.jms.url
- configuration property. When using Joram, its value should be the Joram
- URL joram://host:port where host is the host
- name, and port is the connection port (by default, 16010).
- For SwiftMQ, the value of the URL is similar to the following:
- smqp://host:4001/timeout=10000.
-jonas.services security,jtm,dbm,jms,ejb // The jms service must be in the list -jonas.service.jms.collocated false -jonas.service.jms.url joram://host2:16010 --
As mentioned previously, the default host or default connection port
- number may need to be changed. This requires modifying the
- a3servers.xml configuration file provided by the JOnAS
- delivery in JONAS_ROOT/conf directory. For this, JOnAS must be configured
- with the property jonas.service.jms.collocated set to
- false, and the property
- jonas.service.jms.url set to
- joram://host:port. Additionally, the MOM must have been
- previously launched with the JmsServer command. This command defines a
- Transaction property set to
- fr.dyade.aaa.util.NullTransaction. If the messages need to
- be persistent, replace the
- -DTransaction=fr.dyade.aaa.util.NullTransaction option with
- the -DTransaction=fr.dyade.aaa.util.NTransaction option.
- Refer to the Joram documentation for more details about this command. To
- define a more complex configuration (e.g., distribution, multi-servers),
- refer to the Joram documentation on http://joram.objectweb.org.
There are two Message-driven beans in this example:
-StockHandlerBean
- is a Message-driven bean listening to a topic and receiving Map messages.
- The onMessage method runs in the scope of a transaction started
- by the container. It sends a Text message on a Queue (OrdersQueue) and
- updates a Stock element by decreasing the stock quantity. If the stock
- quantity becomes negative, an exception is received and the current
- transaction is marked for rollback.OrderBean
- is another Message-driven bean listening on the OrdersQueue Queue. On
- receipt of a Text message on this queue, it writes the corresponding
- String as a new line in a file ("Order.txt").
The example also includes a CMP entity bean Stock that
-handles a stock table.
A Stock item is composed of a Stockid (String), which is the primary key, -and a Quantity (int). The method decreaseQuantity(int qty) decreases the -quantity for the corresponding stockid, but can throw a RemoteException -"Negative stock."
- -The client application SampleAppliClient
-is a JMS Client that sends several messages on the topic
-StockHandlerTopic. It uses Map messages with three fields:
-"CustomerId," "ProductId," "Quantity." Before sending messages, this client
-calls the EnvBean
-for creating the StockTable in the database with known values in order
-to check the results of updates at the end of the test. Eleven messages are
-sent, the corresponding transactions are committed, and the last message sent
-causes the transaction to be rolled back.
To compile examples/src/mdb/sampleappli, use Ant
-with the $JONAS_ROOT/examples/src/build.xml file.
jonas.properties
-is the following:
-- jonas.services jmx,security,jtm,dbm,jms,ejb // The jms service must be added - jonas.service.ejb.descriptors sampleappli.jar - jonas.service.jms.topics StockHandlerTopic - jonas.service.jms.queues OrdersQueue - jonas.service.jms.collocated true --This indicates that the JMS Server will be launched in the same JVM as the -JOnAS Server, and the JMS-administered objects
StockHandlerTopic
-(Topic) and OrdersQueue (Queue) will be created and registered
-in JNDI, if not already existing.
-jonas start-
jonas admin -a sampleappli.jar-
jclient sampleappli.SampleAppliClient-
jonas stop-
-The values for max-cache-size should be set accordingly to jonas.service.ejb.maxworkthreads value.
-See Configuring JMS Service.
-
<jonas-ejb-jar> - <jonas-message-driven> - <ejb-name>Mdb</ejb-name> - <jndi-name>mdbTopic</jndi-name> - <max-cache-size>20</max-cache-size> - <min-pool-size>10</min-pool-size> - </jonas-message-driven> - </jonas-ejb-jar> -- - diff --git a/jonas_doc/olddoc/PG_Packaging.html b/jonas_doc/olddoc/PG_Packaging.html deleted file mode 100644 index 5cb776900f40fb4aefcb70474e542381aaedbe92..0000000000000000000000000000000000000000 --- a/jonas_doc/olddoc/PG_Packaging.html +++ /dev/null @@ -1,82 +0,0 @@ - - - - - - -
The target audience for this guide is the Enterprise Bean provider, i.e. -the person in charge of developing the software components on the server -side. It describes how the bean components should be packaged.
- -The content of this guide is the following:
- - -Enterprise Beans are packaged for deployment in a standard Java -programming language Archive file, called an ejb-jar file. This file -must contain the following:
-$JONAS_ROOT/xml/ejb-jar_2_1.xsd or
- http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd
- . This deployment descriptor must be stored with the name
- META-INF/ejb-jar.xml in the ejb-jar file.Before building the ejb-jar file of the Account entity bean example, the -java source files must be compiled to obtain the class files and the two XML -deployment descriptors must be written.
- -Then, the ejb-jar file (OpEB.jar) can be built using the jar -command:
-cd your_bean_class_directory - mkdir META-INF - cp .../eb/*.xml META-INF - jar cvf OpEB.jar sb/*.class META-INF/*.xml -- - diff --git a/jonas_doc/olddoc/PG_Security.html b/jonas_doc/olddoc/PG_Security.html deleted file mode 100644 index 8e07f9467b6bcacd8a29ff020436af4faa85a333..0000000000000000000000000000000000000000 --- a/jonas_doc/olddoc/PG_Security.html +++ /dev/null @@ -1,255 +0,0 @@ - - - - - - -
The target audience for this guide is the Enterprise Bean provider, i.e. -the person in charge of developing the software components on the server -side. It explains how security behavior should be defined.
- -The content of this guide is the following:
-The EJB architecture encourages the Bean programmer to implement the -enterprise bean class without hard-coding the security policies and -mechanisms into the business methods.
- -The application assembler can define a security view of the
-enterprise beans contained in the ejb-jar file.
-The security view consists of a set of security roles. A security
-role is a semantic grouping of permissions for a given type of application
-user that allows that user to successfully use the application.
-The application assembler can define (declaratively in the deployment
-descriptor) method permissions for each security role. A method
-permission is a permission to invoke a specified group of methods for the
-enterprise beans' home and remote interfaces.
-The security roles defined by the application assembler present this
-simplified security view of the enterprise beans application to the deployer;
-the deployer's view of security requirements for the application is the small
-set of security roles, rather than a large number of individual methods.
The application assembler can define one or more security roles -in the deployment descriptor. The application assembler then assigns groups -of methods of the enterprise beans' home and remote interfaces to the -security roles in order to define the security view of the application.
- -The scope of the security roles defined in the security-role
-elements is the ejb-jar file level, and this includes all the enterprise
-beans in the ejb-jar file.
... - <assembly-descriptor> - <security-role> - <role-name>tomcat</role-name> - </security-role> - ... - </assembly-descriptor> -- -
After defining security roles for the enterprise beans in the ejb-jar -file, the application assembler can also specify the methods of the remote -and home interfaces that each security role is allowed to invoke.
- -Method permissions are defined as a binary relationship in the deployment
-descriptor from the set of security roles to the set of methods of the home
-and remote interfaces of the enterprise beans, including all their super
-interfaces (including the methods of the javax.ejb.EJBHome and
-javax.ejb.EJBObject interfaces). The method permissions
-relationship includes the pair (R, M) only if the security role
-R is allowed to invoke the method M.
The application assembler defines the method permissions relationship in
-the deployment descriptor using the method-permission element as
-follows:
method-permission element includes a list of one or
- more security roles and a list of one or more methods. All the listed
- security roles are allowed to invoke all the listed methods. Each
- security role in the list is identified by the role-name
- element, and each method is identified by the method
- element.method-permission elements.method-permission elements.It is possible that some methods are not assigned to any security roles. -This means that these methods can be accessed by anyone.
- -The following example illustrates how security roles are assigned to -methods' permissions in the deployment descriptor:
-... - <method-permission> - <role-name>tomcat</role-name> - <method> - <ejb-name>Op</ejb-name> - <method-name>*</method-name> - </method> - </method-permission> - ... -- -
Because not all security policies can be expressed declaratively, the EJB -architecture also provides a simple programmatic interface that the Bean -programmer can use to access the security context from the business -methods.
- -The javax.ejb.EJBContext interface provides two methods that
-allow the Bean programmer to access security information about the enterprise
-bean's caller.
public interface javax.ejb.EJBContext {
- ...
- //
- // The following two methods allow the EJB class
- // to access security information
- //
- java.security.Principal getCallerPrincipal() ;
- boolean isCallerInRole (String roleName) ;
- ...
-}
-
-
-The purpose of the getCallerPrincipal() method is to allow
-the enterprise bean methods to obtain the current caller principal's name.
-The methods might, for example, use the name as a key to access information
-in a database.
An enterprise bean can invoke the getCallerPrincipal() method
-to obtain a java.security.Principal interface representing the
-current caller. The enterprise bean can then obtain the distinguished name of
-the caller principal using the getName() method of the
-java.security.Principal interface.
The main purpose of the isCallerInRole(String roleName)
-method is to allow the Bean programmer to code the security checks that
-cannot be easily defined declaratively in the deployment descriptor using
-method permissions. Such a check might impose a role-based limit on a
-request, or it might depend on information stored in the database.
The enterprise bean code uses the isCallerInRole(String
-roleName) method to test whether the current caller has been assigned
-to a given security role or not. Security roles are defined by the
-application assembler in the deployment descriptor and are assigned to
-principals by the deployer.
The Bean programmer must declare in the security-role-ref
-elements of the deployment descriptor all the security role names used in the
-enterprise bean code. Declaring the security roles' references in the code
-allows the application assembler or deployer to link the names of the
-security roles used in the code to the actual security roles defined for an
-assembled application through the security-role elements.
... - <enterprise-beans> - ... - <session> - <ejb-nameOp</ejb-name> - <ejb-class>sb.OpBean</ejb-class> - ... - <security-role-ref> - <role-name>role1</role-name> - </security-role-ref> - ... - </session> - ... - </enterprise-beans> - ... -- -
The deployment descriptor in this example indicates that the enterprise
-bean Op makes the security checks using
-isCallerInRole("role1") in at least one of its business
-methods.
If the security-role elements have been defined in the
-deployment descriptor, all the security role references declared in the
-security-role-ref elements must be linked to the security roles
-defined in the security-role elements.
The following deployment descriptor example shows how to link the security
-role references named role1 to the security role named
-tomcat.
... - <enterprise-beans> - ... - <session> - <ejb-name>Op</ejb-name> - <ejb-class>sb.OpBean</ejb-class> - ... - <security-role-ref> - <role-name>role1</role-name> - <role-link>tomcat</role-link> - </security-role-ref> - ... - </session> - ... - </enterprise-beans> - ... -- -
In summary, the role names used in the EJB code (in the isCallerInRole
-method) are, in fact, references to actual security roles, which makes the
-EJB code independent of the security configuration described in the
-deployment descriptor. The programmer makes these role references available
-to the Bean deployer or application assembler via the
-security-role-ref elements included in the session
-or entity elements of the deployment descriptor. Then, the Bean
-deployer or application assembler must map the security roles defined in the
-deployment descriptor to the "specific" roles of the target operational
-environment (e.g. groups on Unix systems). However, this last mapping step is
-not currently available in JOnAS.
The target audience for this guide is the Enterprise Bean provider, i.e. -the person in charge of developing the software components on the server side -and, more specifically, the Session Beans.
- -The content of this guide is the following:
-A Session Bean is composed of the following parts, which are developed by -the Enterprise Bean Provider:
-Note that, according to the EJB 2.0 specification, the couple "Component -Interface and Home Interface" may be either local or remote. Local -Interfaces (Home and Component) are to be used by a client running in the -same JVM as the EJB component. Create and finder methods of a local or remote -home interface return local or remote component interfaces respectively. An -EJB component can have both remote and local interfaces, even if typically -only one type of interface is provided.
- -The description of these elements is provided in the following -sections.
- -Note: in this documentation, the term "Bean" always means "Enterprise -Bean."
- -A session bean object is a short-lived object that executes on behalf of a -single client.There are stateless and stateful session beans. -Stateless beans do not maintain state across method calls. Any instance of -stateless beans can be used by any client at any time. Stateful session beans -maintain state within and between transactions. Each stateful session bean -object is associated with a specific client. A stateful session bean with -container-managed transaction demarcation can optionally implement the -SessionSynchronization interface. In this case, the bean objects will -be informed of transaction boundaries. A rollback could result in a session -bean object's state being inconsistent; in this case, implementing the -SessionSynchronization interface may enable the bean object to update its -state according to the transaction completion status.
- -A Session bean's home interface defines one or more create(...)
-methods. Each create method must be named create and must
-match one of the ejbCreate methods defined in the enterprise Bean class. The
-return type of a create method must be the enterprise Bean's remote interface
-type.
-The home interface of a stateless session bean must have one create
-method that takes no arguments.
All the exceptions defined in the throws clause of an ejbCreate -method must be defined in the throws clause of the matching create -method of the home interface.
- -A remote home interface extends the javax.ejb.EJBHome
-interface, while a local home interface extends the
-javax.ejb.EJBLocalHome interface.
The following examples use a Session Bean named Op.
- public interface OpHome extends EJBHome {
- Op create(String user) throws CreateException, RemoteException;
- }
-
-
-A local home interface could be defined as follows (LocalOp
-being the local component interface of the bean):
public interface LocalOpHome extends EJBLocalHome {
- LocalOp create(String user) throws CreateException;
- }
-
-
-The Component Interface is the client's view of an instance of the session -bean. This interface contains the business methods of the enterprise bean. -The interface must extend the javax.ejb.EJBObject interface if it is -remote, or the javax.ejb.EJBLocalObject if it is local. The methods -defined in a remote component interface must follow the rules for Java RMI -(this means that their arguments and return value must be valid types for -java RMI, and their throws clause must include the -java.rmi.RemoteException). For each method defined in the component -interface, there must be a matching method in the enterprise Bean's class -(same name, same arguments number and types, same return type, and same -exception list, except for RemoteException).
- - public interface Op extends EJBObject {
- public void buy (int Shares) throws RemoteException;
- public int read () throws RemoteException;
- }
-
-
-The same type of component interface could be defined as a local interface -(even if it is not considered good design to define the same interface as -both local and remote):
- public interface LocalOp extends EJBLocalObject {
- public void buy (int Shares);
- public int read ();
- }
-
-
-This class implements the Bean's business methods of the component -interface and the methods of the SessionBean interface, which are -those dedicated to the EJB environment. The class must be defined as public -and may not be abstract. The Session Bean interface methods that the -EJB provider must develop are the following:
-This method is used by the container to pass a reference to the - SessionContext to the bean instance. The container invokes this method on - an instance after the instance has been created. Generally, this method - stores this reference in an instance variable.
-This method is invoked by the container when the instance is in the - process of being removed by the container. Since most session Beans do - not have any resource state to clean up, the implementation of this - method is typically left empty.
-This method is invoked by the container when it wants to passivate the - instance. After this method completes, the instance must be in a state - that allows the container to use the Java Serialization protocol to - externalize and store the instance's state.
-This method is invoked by the container when the instance has just - been reactivated. The instance should acquire any resource that it has - released earlier in the ejbPassivate() method.
-A stateful session Bean with container-managed transaction demarcation can -optionally implement the javax.ejb.SessionSynchronization interface. -This interface can provide the Bean with transaction synchronization -notifications. The Session Synchronization interface methods that the -EJB provider must develop are the following:
-This method notifies a session Bean instance that a new transaction - has started. At this point the instance is already in the transaction and - can do any work it requires within the scope of the transaction.
-This method notifies a session Bean instance that a transaction commit - protocol has completed and tells the instance whether the transaction has - been committed or rolled back.
-This method notifies a session Bean instance that a transaction is - about to be committed.
-package sb;
-
-import java.rmi.RemoteException;
-import javax.ejb.EJBException;
-import javax.ejb.EJBObject;
-import javax.ejb.SessionBean;
-import javax.ejb.SessionContext;
-import javax.ejb.SessionSynchronization;
-import javax.naming.InitialContext;
-import javax.naming.NamingException;
-
-// This is an example of Session Bean, stateful, and synchronized.
-
-public class OpBean implements SessionBean, SessionSynchronization {
-
- protected int total = 0; // actual state of the bean
- protected int newtotal = 0; // value inside Tx, not yet committed.
- protected String clientUser = null;
- protected SessionContext sessionContext = null;
-
- public void ejbCreate(String user) {
- total = 0;
- newtotal = total;
- clientUser = user;
- }
-
- public void ejbActivate() {
- // Nothing to do for this simple example
- }
-
- public void ejbPassivate() {
- // Nothing to do for this simple example
- }
-
- public void ejbRemove() {
- // Nothing to do for this simple example
- }
-
- public void setSessionContext(SessionContext sessionContext) {
- this.sessionContext = sessionContext;
- }
-
- public void afterBegin() {
- newtotal = total;
- }
-
- public void beforeCompletion() {
- // Nothing to do for this simple example
-
- // We can access the bean environment everywhere in the bean,
- // for example here!
- try {
- InitialContext ictx = new InitialContext();
- String value = (String) ictx.lookup("java:comp/env/prop1");
- // value should be the one defined in ejb-jar.xml
- } catch (NamingException e) {
- throw new EJBException(e);
- }
- }
-
- public void afterCompletion(boolean committed) {
- if (committed) {
- total = newtotal;
- } else {
- newtotal = total;
- }
- }
-
- public void buy(int s) {
- newtotal = newtotal + s;
- return;
- }
-
- public int read() {
- return newtotal;
- }
-}
-
-
-<jonas-ejb-jar> - <jonas-session> - <ejb-name>SessSLR</ejb-name> - <jndi-name>EJB/SessHome</jndi-name> - <max-cache-size>20</max-cache-size> - <min-pool-size>10</min-pool-size> - </jonas-session> - </jonas-ejb-jar> -- - diff --git a/jonas_doc/olddoc/PG_Transaction.html b/jonas_doc/olddoc/PG_Transaction.html deleted file mode 100644 index 28603499ad78f395a31112824ed9d7d16fc8c4c2..0000000000000000000000000000000000000000 --- a/jonas_doc/olddoc/PG_Transaction.html +++ /dev/null @@ -1,307 +0,0 @@ - - - - - - -
The target audience for this guide is the Enterprise Bean provider, i.e. -the person in charge of developing the software components on the server -side. It describes how to define the transactional behaviour of an EJB -application.
- -The content of this guide is the following:
-For container-managed transaction management, the transactional behaviour -of an enterprise bean is defined at configuration time and is part of the -assembly-descriptor element of the standard deployment descriptor. It is -possible to define a common behaviour for all the methods of the bean, or to -define the behaviour at the method level. This is done by specifying a -transactional attribute, which can be one of the following:
-| Transaction Attribute | -Client transaction | -Transaction associated with enterprise Bean's - method | -
|---|---|---|
| NotSupported | --
-
- T1 - |
- -
-
- - - |
-
| Required | --
-
- T1 - |
- T2
-
- T1 - |
-
| RequiresNew | --
-
- T1 - |
- T2
-
- T2 - |
-
| Mandatory | --
-
- T1 - |
- error
-
- T1 - |
-
| Supports | --
-
- T1 - |
- -
-
- T1 - |
-
| Never | --
-
- T1 - |
- -
-
- error - |
-
In the deployment descriptor, the specification of the transactional -attributes appears in the assembly-descriptor as follows:
-<assembly-descriptor> - <container-transaction> - <method> - <ejb-name>AccountImpl</ejb-name> - <method-name>*</method-name> - </method> - <trans-attribute>Supports</trans-attribute> - </container-transaction> - <container-transaction> - <method> - <ejb-name>AccountImpl</ejb-name> - <method-name>getBalance</method-name> - </method> - <trans-attribute>Required</trans-attribute> - </container-transaction> - <container-transaction> - <method> - <ejb-name>AccountImpl</ejb-name> - <method-name>setBalance</method-name> - </method> - <trans-attribute>Mandatory</trans-attribute> - </container-transaction> - </assembly-descriptor> -- -
In this example, for all methods of the AccountImpl bean which are not -explicitly specified in a container-transaction element, the default -transactional attribute is Supports (defined at the bean-level), and the -transactional attributes are Required and Mandatory (defined at the -method-name level) for the methods getBalance and setBalance respectively.
- -A bean that manages its transactions itself must set the -transaction-type element in its standard deployment descriptor -to:
-<transaction-type>Bean</transaction-type> -- -
To demarcate the transaction boundaries in a bean with bean-managed -transactions, the bean programmer should use the -javax.transaction.UserTransaction interface, which is defined on an -EJB server object that may be obtained using the -EJBContext.getUserTransaction() method (the SessionContext object or -the EntityContext object depending on whether the method is defined on a -session or on an entity bean). The following example shows a session bean -method "doTxJob" demarcating the transaction boundaries; the UserTransaction -object is obtained from the sessionContext object, which should have been -initialized in the setSessionContext method (refer to the example of the session -bean).
-public void doTxJob() throws RemoteException {
- UserTransaction ut = sessionContext.getUserTransaction();
- ut.begin();
- ... // transactional operations
- ut.commit();
-}
-
-Another way to do this is to use JNDI and to retrieve UserTransaction with -the name java:comp/UserTransaction in the initial context.
- -As explained in the previous section, the transactional behaviour of an -application can be defined in a declarative way or coded in the bean and/or -the client itself (transaction boundaries demarcation). In any case, the -distribution aspects of the transactions are completely transparent to the -bean provider and to the application assembler. This means that a transaction -may involve beans located on several JOnAS servers and that the platform -itself will handle management of the global transaction. It will perform the -two-phase commit protocol between the different servers, and the bean -programmer need do nothing.
- -Once the beans have been developed and the application has been assembled, -it is possible for the deployer and for the administrator to configure the -distribution of the different beans on one or several machines, and within -one or several JOnAS servers. This can be done without impacting either the -beans code or their deployment descriptors. The distributed configuration is -specified at launch time. In the environment properties of an EJB server, the -following can be specified:
-To achieve this goal, two properties must be set in the -jonas.properties file, jonas.service.ejb.descriptors and -jonas.service.jtm.remote. The first one lists the beans that will be -handled on this server (by specifying the name of their ejb-jar files), and -the second one sets the Java Transaction Monitor (JTM) launching mode:
-Example:
-jonas.service.ejb.descriptors Bean1.jar, Bean2.jar - jonas.service.jtm.remote false -- -
The Java Transaction Monitor can run outside any EJB server, in which case -it can be launched in a stand-alone mode using the following command:
-TMServer- - - -
Using these configuration facilities, it is possible to adapt the beans -distribution to the resources (cpu and data) location, for optimizing -performance.
- -The following figure illustrates four cases of distribution configuration -for three beans.
- -
These different configuration cases may be obtained by launching the JOnAS -servers and eventually the JTM (case 3) with the adequate properties. The -rational when choosing one of these configurations is resources location and -load balancing. However, consider the following pointers:
-The target audience for this guide is the Web component provider, i.e. the -person in charge of developing the Web components on the server side. It -describes how the Web component provider should build the deployment -descriptors of its Web components and how the web components should be -packaged.
- -The content of this guide is the following:
-A Web Component is a generic term which denotes both JSP pages and
-Servlets. Web components are packaged in a .war file and can be
-deployed in a JOnAS server via the web container service. Web
-components can be integrated in a J2EE application by packing the
-.war file in an .ear file (refer to the J2EE Application Programmer's
-Guide).
The JOnAS distribution includes a Web application example: The EarSample example.
The directory structure of this application is the following:
- -| etc/xml | -contains the web.xml file describing the web application | -
| etc/resources/web | -contains html pages and images; JSP pages can also be placed - here. | -
| src/org/objectweb/earsample/servlets | -servlet sources | -
| src/org/objectweb/earsample/beans | -beans sources | -
The bean directory is not needed if beans coming from another application -will be used.
- -Java Server Pages (JSP) is a technology that allows regular, static HTML, -to be mixed with dynamically-generated HTML written in Java programming -language for encapsulating the logic that generates the content for the page. -Refer to the Java Server -PagesTM and the Quickstart guide for -more details.
- -The following example shows a sample JSP page that lists the content of a -cart.
- <!-- Get the session -->
- <%@ page session="true" %>
-
- <!-- The import to use -->
- <%@ page import="java.util.Enumeration" %>
- <%@ page import="java.util.Vector" %>
-
- <html>
- <body bgcolor="white">
- <h1>Content of your cart</h1><br>
- <table>
- <!-- The header of the table -->
- <tr bgcolor="black">
- <td><font color="lightgreen">Product Reference</font></td>
- <td><font color="lightgreen">Product Name</font></td>
- <td><font color="lightgreen">Product Price</font></td>
- </tr>
-
- <!-- Each iteration of the loop display a line of the table -->
- <%
- Cart cart = (Cart) session.getAttribute("cart");
- Vector products = cart.getProducts();
- Enumeration enum = products.elements();
- // loop through the enumeration
- while (enum.hasMoreElements()) {
- Product prod = (Product) enum.nextElement();
- %>
- <tr>
- <td><%=prod.getReference()%></td>
- <td><%=prod.getName()%></td>
- <td><%=prod.getPrice()%></td>
- </tr>
- <%
- } // end loop
- %>
- </table>
- </body>
- </html>
-
-
-It is a good idea to hide all the mechanisms for accessing EJBs from JSP
-pages by using a proxy java bean, referenced in the JSP page by the
-usebean special tag. This technique is shown in the alarm example, where the .jsp files
-communicate with the EJB via a proxy java bean ViewProxy.java.
Servlets are modules of Java code that run in an application server for -answering client requests. Servlets are not tied to a specific client-server -protocol. However, they are most commonly used with HTTP, and the word -"Servlet" is often used as referring to an "HTTP Servlet."
- -Servlets make use of the Java standard extension classes in the packages
-javax.servlet (the basic Servlet framework) and
-javax.servlet.http (extensions of the Servlet framework for
-Servlets that answer HTTP requests).
Typical uses for HTTP Servlets include:
-For more details refer to the JavaTM Servlet -Technology and the Servlets -tutorial.
- -The following example is a sample of a Servlet that lists the content of a
-cart.
-This example is the servlet version of the previous JSP page example.
import java.util.Enumeration;
- import java.util.Vector;
- import java.io.PrintWriter;
- import java.io.IOException;
- import javax.servlet.ServletException;
- import javax.servlet.http.HttpServlet;
- import javax.servlet.http.HttpServletRequest;
- import javax.servlet.http.HttpServletResponse;
- import javax.servlet.http.HttpSession;
-
- public class GetCartServlet extends HttpServlet {
-
- protected void doGet(HttpServletRequest req, HttpServletResponse res)
- throws ServletException, IOException {
-
- res.setContentType("text/html");
- PrintWriter out = res.getWriter();
-
- out.println("<html><head><title>Your cart</title></head>");
- out.println("<body>");
- out.println("<h1>Content of your cart</h1><br>");
- out.println("<table>");
-
- // The header of the table
- out.println("<tr>");
- out.println("<td><font color="lightgreen">Product Reference</font></td>");
- out.println("<td><font color="lightgreen">Product Name</font></td>");
- out.println("<td><font color="lightgreen">Product Price</font></td>");
- out.println("</tr>");
-
- // Each iteration of the loop display a line of the table
- HttpSession session = req.getSession(true);
- Cart cart = (Cart) session.getAttribute("cart");
- Vector products = cart.getProducts();
- Enumeration enum = products.elements();
- while (enum.hasMoreElements()) {
- Product prod = (Product) enum.nextElement();
- int prodId = prod.getReference();
- String prodName = prod.getName();
- float prodPrice = prod.getPrice();
- out.println("<tr>");
- out.println("<td>" + prodId + </td>);
- out.println("<td>" + prodName + </td>);
- out.println("<td>" + prodPrice + </td>);
- out.println("</tr>");
- }
-
- out.println("</table>");
- out.println("</body>");
- out.println("</html>");
- out.close();
- }
- }
-
-
-The following sections describe:
-The EarSample example provided in the JOnAS
-distribution.
-
-import javax.naming.Context;
-import javax.naming.InitialContext;
-
-//remote interface
-import org.objectweb.earsample.beans.secusb.Op;
-import org.objectweb.earsample.beans.secusb.OpHome;
-
- Context initialContext = null;
- try {
- initialContext = new InitialContext();
- } catch (Exception e) {
- out.print("<li>Cannot get initial context for JNDI: ");
- out.println(e + "</li>");
- return;
- }
- // Connecting to OpHome thru JNDI
- OpHome opHome = null;
- try {
- opHome = (OpHome) PortableRemoteObject.narrow(initialContext.lookup
- ("java:comp/env/ejb/Op"),OpHome.class);
- } catch (Exception e) {
- out.println("<li>Cannot lookup java:comp/env/ejb/Op: " + e + "</li>");
- return;
- }
- // OpBean creation
- Op op = null;
- try {
- op = opHome.create("User1");
- } catch (Exception e) {
- out.println("<li>Cannot create OpBean: " + e + "</li>");
- return;
- }
-Note that the following elements must be set in the web.xml file
-tied to this web application:
-<ejb-ref> - <ejb-ref-name>ejb/Op</ejb-ref-name> - <ejb-ref-type>Session</ejb-ref-type> - <home>org.objectweb.earsample.beans.secusb.OpHome</home> - <remote>org.objectweb.earsample.beans.secusb.Op</remote> - <ejb-link>secusb.jar#Op</ejb-link> - </ejb-ref>- -
//local interfaces
-import org.objectweb.earsample.beans.secusb.OpLocal;
-import org.objectweb.earsample.beans.secusb.OpLocalHome;
-
-
- // Connecting to OpLocalHome thru JNDI
- OpLocalHome opLocalHome = null;
- try {
- opLocalHome = (OpLocalHome)
- initialContext.lookup("java:comp/env/ejb/OpLocal");
- } catch (Exception e) {
- out.println("<li>Cannot lookup java:comp/env/ejb/OpLocal: " + e + "</li>");
- return;
- }
-This is found in the web.xml file:
-<ejb-local-ref> - <ejb-ref-name>ejb/OpLocal</ejb-ref-name> - <ejb-ref-type>Session</ejb-ref-type> - <local-home>org.objectweb.earsample.beans.secusb.OpLocalHome</local-home> - <local>org.objectweb.earsample.beans.secusb.OpLocal</local> - <ejb-link>secusb.jar#Op</ejb-link> - </ejb-local-ref>- -
String envEntry = null;
- try {
- envEntry = (String) initialContext.lookup("java:comp/env/envEntryString");
- } catch (Exception e) {
- out.println("<li>Cannot get env-entry on JNDI " + e + "</li>");
- return;
- }
-This is the corresponding part of the web.xml file:
-<env-entry> - <env-entry-name>envEntryString</env-entry-name> - <env-entry-value>This is a string from the env-entry</env-entry-value> - <env-entry-type>java.lang.String</env-entry-type> - </env-entry>- -
import javax.transaction.UserTransaction;
-
- // We want to start transactions from client: get UserTransaction
- UserTransaction utx = null;
- try {
- utx = (UserTransaction) initialContext.lookup("java:comp/UserTransaction");
- } catch (Exception e) {
- out.println("<li>Cannot lookup java:comp/UserTransaction: " + e + "</li>");
- return;
- }
-
- try {
- utx.begin();
- opLocal.buy(10);
- opLocal.buy(20);
- utx.commit();
-
- } catch (Exception e) {
- out.println("<li>exception during 1st Tx: " + e + "</li>");
- return;
- }
-
-The Web component programmer is responsible for providing the deployment
-descriptor associated with the developed web components. The Web component
-provider's responsibilities and the application assembler's responsibilities
-are to provide an XML deployment descriptor that conforms to the deployment
-descriptor's XML schema as defined in the Java TM Servlet
-Specification Version 2.4. (Refer to
-$JONAS_ROOT/xml/web-app_2_4.xsd or
-http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd).
To customize the Web components, information not defined in the standard
-XML deployment descriptor may be needed. For example, the information may
-include the mapping of the name of referenced resources to its JNDI name.
-This information can be specified during the deployment phase, within another
-XML deployment descriptor that is specific to JOnAS. The JOnAS-specific
-deployment descriptor's XML schema is located in
-$JONAS_ROOT/xml/jonas-web-app_X_Y.xsd. The file name of the
-JOnAS-specific XML deployment descriptor must be the file name of the
-standard XML deployment descriptor prefixed by 'jonas-'.
The parser gets the specified schema via the classpath (schemas are packaged -in the $JONAS_ROOT/lib/common/ow_jonas.jar file).
- -The standard deployment descriptor (web.xml) should contain structural -information that includes the following:
-The JOnAS-specific deployment descriptor (jonas-web.xml) may contain -information that includes:
-<host> element: If the configuration file of the web container -contains virtual hosts, the host on which the WAR file is deployed can be -set.
- -<context-root> element: The name of the context on which the -application will be deployed should be specified. If it is not specified, the -context-root used can be one of the following:
-<java2-delegation-model> element: Set the compliance to the java 2 -delegation model.
-<?xml version="1.0" encoding="ISO-8859-1"?> - -<web-app xmlns="http://java.sun.com/xml/ns/j2ee" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" - version="2.4"> - - <servlet> - <servlet-name>Op</servlet-name> - <servlet-class>org.objectweb.earsample.servlets.ServletOp</servlet-class> - </servlet> - - <servlet-mapping> - <servlet-name>Op</servlet-name> - <url-pattern>/secured/Op</url-pattern> - </servlet-mapping> - - <security-constraint> - <web-resource-collection> - <web-resource-name>Protected Area</web-resource-name> - <!-- Define the context-relative URL(s) to be protected --> - <url-pattern>/secured/*</url-pattern> - <!-- If you list http methods, only those methods are protected --> - <http-method>DELETE</http-method> - <http-method>GET</http-method> - <http-method>POST</http-method> - <http-method>PUT</http-method> - </web-resource-collection> - <auth-constraint> - <!-- Anyone with one of the listed roles may access this area --> - <role-name>tomcat</role-name> - <role-name>role1</role-name> - </auth-constraint> - </security-constraint> - - <!-- Default login configuration uses BASIC authentication --> - <login-config> - <auth-method>BASIC</auth-method> - <realm-name>Example Basic Authentication Area</realm-name> - </login-config> - - <env-entry> - <env-entry-name>envEntryString</env-entry-name> - <env-entry-value>This is a string from the env-entry</env-entry-value> - <env-entry-type>java.lang.String</env-entry-type> - </env-entry> - - <!-- reference on a remote bean without ejb-link--> - <ejb-ref> - <ejb-ref-name>ejb/Op</ejb-ref-name> - <ejb-ref-type>Session</ejb-ref-type> - <home>org.objectweb.earsample.beans.secusb.OpHome</home> - <remote>org.objectweb.earsample.beans.secusb.Op</remote> - </ejb-ref> - - <!-- reference on a remote bean using ejb-link--> - <ejb-ref> - <ejb-ref-name>ejb/EjbLinkOp</ejb-ref-name> - <ejb-ref-type>Session</ejb-ref-type> - <home>org.objectweb.earsample.beans.secusb.OpHome</home> - <remote>org.objectweb.earsample.beans.secusb.Op</remote> - <ejb-link>secusb.jar#Op</ejb-link> - </ejb-ref> - - <!-- reference on a local bean --> - <ejb-local-ref> - <ejb-ref-name>ejb/OpLocal</ejb-ref-name> - <ejb-ref-type>Session</ejb-ref-type> - <local-home>org.objectweb.earsample.beans.secusb.OpLocalHome</local-home> - <local>org.objectweb.earsample.beans.secusb.OpLocal</local> - <ejb-link>secusb.jar#Op</ejb-link> - </ejb-local-ref> -</web-app> --
<?xml version="1.0" encoding="ISO-8859-1"?> - -<jonas-web-app xmlns="http://www.objectweb.org/jonas/ns" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://www.objectweb.org/jonas/ns - http://www.objectweb.org/jonas/ns/jonas-web-app_4_0.xsd" > - - <!-- Mapping between the referenced bean and its JNDI name, override the ejb-link if - there is one in the associated ejb-ref in the standard Web Deployment Descriptor --> - <jonas-ejb-ref> - <ejb-ref-name>ejb/Op</ejb-ref-name> - <jndi-name>OpHome</jndi-name> - </jonas-ejb-ref> - - <!-- the virtual host on which deploy the web application --> - <host>localhost</host> - - <!-- the context root on which deploy the web application --> - <context-root>web-application</context-root> -</jonas-web-app> - --
Although some characters, such as ">", are legal, it is good practice -to replace them with XML entity references. The following is a list of the -predefined entity references for XML:
- -| < | -< | -less than | -
| > | -> | -greater than | -
| & | -& | -ampersand | -
| ' | -' | -apostrophe | -
| " | -" | -quotation mark | -
Web components are packaged for deployment in a standard Java programming -language Archive file called a war file (Web ARchive), which is a -jar similar to the package used for Java class libraries. A -war has a specific hierarchical directory structure. The top-level -directory of a war is the document root of the application.
- -The document root is where JSP pages, client-side classes and archives, -and static web resources are stored. The document root contains a -subdirectory called WEB-INF, which contains the following files and -directories:
-Before building a war file, the java source files must be compiled -to obtain the class files (located in the WEB-INF/classes directory) -and the two XML deployment descriptors must be written.
- -Then, the war file (<web-application>.war) is built using the -jar command:
-cd <your_webapp_directory> - jar cvf <web-application>.war * -- -
During the development process, an 'unpacked version' of the war file can -be used. Refer to Configuring Web -Container Service for information about how to use directories for the -web application.
- - diff --git a/jonas_doc/olddoc/Services.html b/jonas_doc/olddoc/Services.html deleted file mode 100644 index afaf15ff649e5ba6d29ae7ffbbb81d751f62212f..0000000000000000000000000000000000000000 --- a/jonas_doc/olddoc/Services.html +++ /dev/null @@ -1,229 +0,0 @@ - - - - - - -The content of this guide is the following:
- - -This chapter is intended for advanced JOnAS users who require that some -"external" services run along with the JOnAS server. A service is something -that may be initialized, started, and stopped. JOnAS itself already defines a -set of services, some of which are cornerstones of the JONAS Server. The -JOnAS pre-defined services are listed in Configuring JOnAS services.
- -J2EE application developers may need to access other services, for example -another Web container or a Versant container, for their components. Thus, it -is important that such services be able to run along with the application -server. To achieve this, it is possible to define them as JOnAS services.
- -This chapter describes how to define a new JOnAS service and how to -specify which service should be started with the JOnAS server.
- -The customary way to define a new JOnAS service is to encapsulate it in a -class whose interface is known by JOnAS. More precisely, such a class -provides a way to initialize, start, and stop the service. Then, the -jonas.properties file must be modified to make JOnAS aware of this -service.
- -A JOnAS service is represented by a class that implements the interface
-org.objectweb.jonas.service.Service, and, thus should implement
-the following methods:
public void init(Context ctx) throws ServiceException;public void start() throws ServiceException;public void stop() throws ServiceException;public boolean isStarted();public String getName();public void setName(String name);It should also define a public constructor with no argument.
- -These methods will be called by JOnAS for initializing, starting, and
-stopping the service. Configuration parameters are provided to the
-initialization method through a naming context. This naming context is built
-from properties defined in the jonas.properties file as
-explained in the following section.
The Service class should look like the following:
-package a.b;- -
import javax.naming.Context;
import javax.naming.NamingException;
import org.objectweb.jonas.service.Service;
import org.objectweb.jonas.service.ServiceException;
.....
public class MyService implements Service {
private String name = null;
private boolean started = false;
.....
public void init(Context ctx) throws ServiceException {
try {
String p1 = (String) ctx.lookup("jonas.service.serv1.p1");
.....
} catch (NamingException e) {
throw new ServiceException("....", e);
}
.....
}
public void start() throws ServiceException {
.....
this.started = true;
}
public void stop() throws ServiceException {
if (this.started) {
this.started = false;
.....
}
}
public boolean isStarted() {
return this.started;
}
public String getName() {
return this.name;
}
public void setName(String name) {
this.name = name;
}
}
The service is defined and its initialization parameters specified in the
-jonas.properties file. First, choose a name for the service
-(e.g. "serv1"), then do the following:
jonas.services property; this
- property defines the set of services (comma-separated) that will be
- started with JOnAS, in the order of this list.jonas.service.serv1.class property specifying the
- service class.jonas.service.serv1.XXX properties specifying
- the service initialization parameters, as will be made available to the
- service class via the Context argument of the init
- method.This is illustrated as follows:
-jonas.services .......,serv1- -
jonas.service.serv1.class a.b.MyService
jonas.service.serv1.p1 value
jonas.properties. With
-this name, it is possible to get a reference on the service implementation
-class by using the ServiceManager method: getService(name). The
-following is an example of accessing a Service:
-import org.objectweb.jonas.service.ServiceException;- -
import org.objectweb.jonas.service.ServiceManager;
MyService sv = null;
// Get a reference on MyService.
try {
sv = (MyService) ServiceManager.getInstance().getService("serv1");
} catch (ServiceException e) {
Trace.errln("Cannot find MyService:"+e);
}
Package the class of the service into a .jar file and add the jar in the
-JONAS_ROOT/lib/ext directory.
-All the libraries required by the service can also be placed in this
-directory.
Refer to the JOnAS sources for more details about the classes mentioned in -this section.
- -The existing JOnAS services are the following:
- -| Service name | -Service class | -
|---|---|
| registry | -RegistryServiceImpl | -
| ejb | -EJBServiceImpl | -
| web | -CatalinaJWebContainerServiceImpl / - JettyJWebContainerServiceImpl | -
| ear | -EarServiceImpl | -
| dbm | -DataBaseServiceImpl | -
| jms | -JmsServiceImpl | -
| jmx | -JmxServiceImpl | -
| jtm | -TransactionServiceImpl | -
| MailServiceImpl | -|
| resource | -ResourceServiceImpl | -
| security | -JonasSecurityServiceImpl | -
| ws - |
- AxisWSService - |
-
If all of these services are required, they will be launched in the
-following order: registry, jmx, security,
-jtm,dbm,mail,jms,resource,ejb, ws,
-web, ear.
-jmx, security, dbm, mail, resource are
-optional when you are using service ejb.
registry must be launched first.
-(Note that for reasons of compatability with previous versions of JOnAS, if
-registry is unintentionally not set as the first service to launch,
-JOnAS will automatically launch the registry service.)
A jonas.properties file looks like the following:
.....- -
.....
jonas.services registry,jmx,security,jtm,dbm,mail,jms,ejb,resource,serv1
jonas.service.registry.class org.objectweb.jonas.registry.RegistryServiceImpl
jonas.service.registry.mode automatic
jonas.service.dbm.class org.objectweb.jonas.dbm.DataBaseServiceImpl
jonas.service.dbm.datasources Oracle1
jonas.service.ejb.class org.objectweb.jonas.container.EJBServiceImpl
jonas.service.ejb.descriptors ejb-jar.jar
jonas.service.ejb.parsingwithvalidation true
jonas.service.ejb.mdbthreadpoolsize 10
jonas.service.web.class org.objectweb.jonas.web.catalina.CatalinaJWebContainerServiceImpl
jonas.service.web.descriptors war.war
jonas.service.web.parsingwithvalidation true
jonas.service.ear.class org.objectweb.jonas.ear.EarServiceImpl
jonas.service.ear.descriptors j2ee-application.ear
jonas.service.ear.parsingwithvalidation true
jonas.service.jms.class org.objectweb.jonas.jms.JmsServiceImpl
jonas.service.jms.mom org.objectweb.jonas_jms.JmsAdminForJoram
jonas.service.jms.collocated true
jonas.service.jms.url joram://localhost:16010
jonas.service.jmx.class org.objectweb.jonas.jmx.JmxServiceImpl
jonas.service.jtm.class org.objectweb.jonas.jtm.TransactionServiceImpl
jonas.service.jtm.remote false
jonas.service.jtm.timeout 60
jonas.service.mail.class org.objectweb.jonas.mail.MailServiceImpl
jonas.service.mail.factories MailSession1
jonas.service.security.class org.objectweb.jonas.security.JonasSecurityServiceImpl
jonas.service.resource.class org.objectweb.jonas.resource.ResourceServiceImpl
jonas.service.resource.resources MyRA
jonas.service.serv1.class a.b.MyService
jonas.service.serv1.p1 John
The org.objectweb.jonas.service.ServiceException exception is
-defined for Services. Its type is java.lang.RuntimeException.
-and it can encapsulate any java.lang.Throwable.
The org.objectweb.jonas.service.ServiceManager class is
-responsible for creating, initializing, and launching the services. It can
-also return a service from its name and list all the services.
The <jonas> nested element uses the
-GenIC-specific tool to build JOnAS-specific stubs and skeletons
-and construct a JAR file which may be deployed to the JOnAS Application
-Server. The build process will always determine if the EJB stubs/skeletons
-and the EJB-JAR file are up to date, and it will perform the minimum amount
-of work required.
A naming convention for the EJB descriptors is most commonly used to
-specify the name for the completed JAR file. For example, if the EJB
-descriptor ejb/Account-ejb-jar.xml is located in the descriptor
-directory, the <jonas> element will search for a
-JOnAS-specific EJB descriptor file named
-ejb/Account-jonas-ejb-jar.xml, and a JAR file named
-ejb/Account.jar will be written in the destination directory.
-The <jonas> element can also use the JOnAS naming
-convention. Using the same example, the EJB descriptor can also be named
-ejb/Account.xml (no base name terminator here) in the descriptor
-directory. The <jonas> element will then search for a
-JOnAS-specific EJB descriptor file called ejb/jonas-Account.xml.
-This convention does not strictly follow the ejb-jar naming convention
-recommendation, but it is supported for backward compatibility with previous
-version of JOnAS.
Note that when the EJB descriptors are added to the JAR file, they are
-automatically renamed META-INF/ejb-jar.xml and
-META-INF/jonas-ejb-jar.xml.
Furthermore, this naming behaviour can be modified by specifying -attributes in the ejbjar task (for example, basejarname, basenameterminator, -and flatdestdir) as well as the iplanet element (for example, suffix). Refer -to the appropriate documentation for more details.
- -| Attribute | -Description | -Required | -
|---|---|---|
| destdir | -The base directory into which the generated JAR files
- will be written. Each JAR file is written in directories which
- correspond to their location within the "descriptordir"
- namespace. |
- Yes | -
| jonasroot | -The root directory for JOnAS. | -Yes | -
| jonasbase | -The base directory for JOnAS. If omitted, it defaults
- to jonasroot. |
- No | -
| classpath | -The classpath used when generating EJB stubs and - skeletons. If omitted, the classpath specified in the "ejbjar" parent - task will be used. If specified, the classpath elements will be - prefixed to the classpath specified in the parent "ejbjar" task. A - nested "classpath" elements can also be used. Note that the needed - JOnAS JAR files are automatically added to the classpath. | -No | -
| keepgenerated | -true if the intermediate Java source
- files generated by GenIC must not be deleted. If omitted, it defaults
- to false. |
- No | -
| nofastrmic | -if true, the external RMIC compiler is used
- by GenIC. The default is false, which means the internal
- fast RMIC compiler is used. |
- No | -
| nocompil | -true if the generated source files must
- not be compiled via the java and rmi compilers. If omitted, it
- defaults to false. |
- No | -
| novalidation | -true if the XML deployment descriptors
- must be parsed without validation. If omitted, it defaults to
- false. |
- No | -
| javac | -Java compiler to use. If omitted, it defaults to the
- value of build.compiler property. |
- No | -
| javacopts | -Options to pass to the java compiler. | -No | -
| protocols | -Comma-separated list of protocols (chosen within
- jeremie, jrmp, iiop, cmi) for which stubs should be generated.
- Default is jrmp,jeremie. |
- No | -
| rmicopts | -Options to pass to the rmi compiler. | -No | -
| verbose | -Indicates whether or not to use -verbose switch. If
- omitted, it defaults to false. |
- No | -
| additionalargs | -Add additional args to GenIC. | -No | -
| keepgeneric | -true if the generic JAR file used as
- input to GenIC must be retained. If omitted, it defaults to
- false. |
- No | -
| suffix | -String value appended to the JAR filename when creating each JAR. - If omitted, it defaults to ".jar". | -No | -
| nogenic | -If this attribute is set to true, JOnAS's
- GenIC will not be run on the EJB JAR. Use this if you prefer to run
- GenIC at deployment time. If omitted, it defaults to
- false. |
- No | -
| jvmopts | -Additional args to pass to the GenIC JVM. | -No | -
| invokecmd | -If this attribute is set to true, GenIC will
- use the Javac sun class to avoid using 'javac' command line. This is
- useful for users getting 'java.io.Exception CreateProcess' because of too
- long command lines. Defaults to false. |
- No | -
As noted above, the jonas element supports additional <classpath> -nested elements.
- -
-Note : To avoid java.lang.OutOfMemoryError, the element
-jvmopts can be used to change the default memory usage.
-
This example shows ejbjar being used to generate deployment jars using a -JOnAS EJB container. This example requires the naming standard to be used for -the deployment descriptors. Using this format creates a EJB JAR file for each -variation of '*-jar.xml' that is located in the deployment descriptor -directory.
- <ejbjar srcdir="${build.classes}"
- descriptordir="${descriptor.dir}">
- <jonas destdir="${deploymentjars.dir}"
- jonasroot="${jonas.root}"
- protocols="jrmp,iiop"/>
- <include name="**/*.xml"/>
- <exclude name="**/jonas-*.xml"/>
- <support dir="${build.classes}">
- <include name="**/*.class"/>
- </support>
- </ejbjar>
-
-This example shows ejbjar being used to generate a single deployment jar -using a JOnAS EJB container. This example does require the deployment -descriptors to use the naming standard. This creates only one ejb jar file - -'TheEJBJar.jar'.
- <ejbjar srcdir="${build.classes}"
- descriptordir="${descriptor.dir}"
- basejarname="TheEJBJar">
- <jonas destdir="${deploymentjars.dir}"
- jonasroot="${jonas.root}"
- suffix=".jar"
- protocols="${genic.protocols}"/>
- <include name="**/ejb-jar.xml"/>
- <exclude name="**/jonas-ejb-jar.xml"/>
- </ejbjar>
-
-
-Previous versions of the JOnAS EjbJar Ant task have some -limitations—especially when you are developing webservices.
- -In previous versions of JOnAS, jonas-ejb-jar constructed the JAR for you, using
-information gathered from the ejb-jar.xml and from the classes themselves
-(dependencies using BCEL).
-But if you have a Session Bean exposed as a webservice,
-you want to have more files in your archive (webservices.xml,
-JAX-RPC mapping file, WSDL + imported WSDL
-definitions + imported XML Schema).
The older task did not package these files inside the archive, and -therefore, when GenIC loaded the descriptors, some dependencies were -missing, causing GenIC to throw an exception.
- -The solution is to let the developer create the JAR file, so that -the exact content of the file can be controlled.
- -The file should have at least the following content: -
- -Notice that webservices files are optional. -
- -The genic task supports most attributes of the
-jonas-ejb-jar task.
Differences:
-destdir: JAR files are directly modifiedclasspath: classpath is now set as inner elementnovalidation: validation attribute is used nowkeepgeneric: not meaningful (input JAR is already specific)suffix: not meaningful (no JAR generated)nogenic: not meaningful (we want to run GenIC)| Attribute | -Description | -Required | -
|---|---|---|
| jonasroot | -The root directory for JOnAS. | -Yes (Can be read from ${jonas.root} property if not set) | - -
| jonasbase | -The base directory for JOnAS. If omitted, it defaults
- to jonasroot. |
- No | -
| keepgenerated | -true if the intermediate Java source
- files generated by GenIC must not be deleted. If omitted, it defaults
- to false. |
- No | -
| nofastrmic | -if true, the external RMIC compiler is used
- by GenIC. The default is false, which means the internal
- fast RMIC compiler is used. |
- No | -
| nocompil | -true if the generated source files must
- not be compiled via the Java and RMI compilers. If omitted, it
- defaults to false. |
- No | -
| validation | -true if the XML deployment descriptors
- must be parsed with validation. If omitted, it defaults to
- true. |
- No | -
| javac | -Java compiler to use. If omitted, it defaults to the
- value of build.compiler property. |
- No | -
| javacopts | - -Options to pass to the Java compiler. | -No | -
| protocols | -Comma-separated list of protocols (chosen from
- jeremie, jrmp, iiop, cmi) for which stubs should be generated.
- Default is jrmp,jeremie. |
-
- No | -
| rmicopts | -Options to pass to the RMI compiler. | -No | -
| verbose | -Indicates whether or not to use -verbose switch. If
- omitted, it defaults to false. |
- No | -
| additionalargs | -Add additional arguments to GenIC. | -No | -
| jvmopts | -Additional arguments to pass to the GenIC JVM. | - -No | -
| jvmdebug | -Indicates whether you want to debug the forked JVM; it
- defaults to false. The JVM will be suspended and waiting
- a connection on port 12345. |
- No | - -
| invokecmd | -If this attribute is set to true, GenIC will
- use the Javac sun class to avoid using 'javac' command line. This is
- useful for users getting 'java.io.Exception CreateProcess' because of too
- long command lines. Defaults to false. |
- No | -
| Nested Element | -Description | -Required | -
|---|---|---|
| classpath | -The additional classpath entries used when generating EJB stubs and - skeletons. | -No | -
| fileset | -Points out the ejb-jars that will be processed by GenIC. - Note that you can add as many filesets as you want (useful if - your JARs are in different directories). | -Yes (at least 1) | -
<taskdef name="genic"
- classname="org.objectweb.jonas.ant.GenICTask"
- classpath="${jonas.root}/lib/common/ow_jonas_ant.jar" />
-
-
-<jar destfile="${temp.ejbjars.dir}/my-ejbjar.jar">
- <metainf dir="${etc.dir}/META-INF" />
-
- <fileset dir="${classes.dir}">
- <include name="org/objectweb/jonas/myejbjar/*.class" />
- </fileset>
-</jar>
-
-
-<genic keepgenerated="true"
- protocols="${protocols.names}">
-
- <fileset dir="${temp.dir}">
- <include name="ejbjars/my-ejbjar.jar" />
- </fileset>
-</genic>
-
-The intent of the cluster daemon is to enable the remote control of the JOnAS clustered -instances through a JMX interface.
- -In a cluster configuration, the cluster daemon is the bootstrap of the JOnAS instances.
- -There is at least one cluster daemon instance per machine.
- -
In the same manner as a classic JOnAS instance, the cluster daemon reads its configuration -in a directory pointed to by a JONAS_BASE variable (or JONAS_ROOT if JONAS_BASE is not set). -All the default JONAS_BASE subdirectories and files are not required; the mandatory ones are:
- -| element | -description | -
|---|---|
| $JONAS_BASE/conf | -Configuration directory | -
| $JONAS_BASE/logs | -Log directory | -
| $JONAS_BASE/conf/carol.properties | -Carol configuration file describing the protocol and its parameters (used for the JMX interface) | -
| $JONAS_BASE/conf/trace.properties | -Trace/Error log configuration file | -
| $JONAS_BASE/conf/jonas.properties | -This file must be present for enabling the cluster daemon starting but - its content is not read, the file can be empty - | -
| $JONAS_BASE/conf/clusterd.xml | -Cluster daemon configuration file, lists the local JOnAS instances and describes - their environment (see below) | -
The JOnAS instances controlled by a cluster daemon are configured in the clusterd.xml file.
- -<?xml version="1.0"?> -<cluster-daemon xmlns="http://www.objectweb.org/jonas/ns" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://www.objectweb.org/jonas/ns - http://www.objectweb.org/jonas/ns/jonas-clusterd_4_8.xsd"> - - <name>cd1</name> - <domain-name>domainSample</domain-name> - <jonas-interaction-mode>loosely-coupled</jonas-interaction-mode> - - <server> - <name>node1</name> - <description>Web instance</description> - <java-home>/usr/java/jdk-ia32/sun/j2sdk1.4.2_10</java-home> - <jonas-root>/home/pelletib/pkg/jonas_root_sb48</jonas-root> - <jonas-base>/home/pelletib/tmp/newjc48/jb1</jonas-base> - <xprm></xprm> - <auto-boot>false</auto-boot> - <jonas-cmd></jonas-cmd> - </server> - -... - -</cluster-daemon> - -- -
| element | -description | -
|---|---|
| name | -Cluster daemon instance name. Used for building the connector url. | -
| domain-name | -Domain name to use for launching the JOnAS instance when it is not specified in the start command | -
| jonas-interaction-mode | -Starting mode of the JOnAS instances: loosely-coupled corresponds to background and tighly-coupled
- corresponds to foreground |
-
| server/name | -Name of the JOnAS instance | -
| server/description | -Description of the JOnAS instance | -
| server/java-home | -JDK home directory to use for launching the JOnAS instance | -
| server/jonas-root | -JOnAS binaries directory to use for launching the JOnAS instance | -
| server/jonas-base | -JOnAS configuration directory to use for launching the JOnAS instance | -
| server/xprms | -JVM parameters to set when launching the JOnAS instance | -
| server/auto-boot | -If true, start the JOnAS instance when launching the cluster daemon | -
| server/jonas-cmd | -Optional parameter. If set, specifies the script to use for starting/stopping the JOnAS instance. This user script can set the required environnement and perform some pre or post processing. By default, the jonas command is used. | -
The cluster daemons must be specified and associated to the JOnAS instances in the domain.xml file
-for permitting the remote control of the cluster.
-... -<cluster-daemon> - <name>cd1</name> - <description>cluster daemon 1</description> - <location> - <url>service:jmx:rmi://host/jndi/rmi://host:port/jrmpconnector_cd</url> - </location> -</cluster-daemon> -... -<server> - <name>node1</name> - <cluster-daemon>cd1</cluster-daemon> - ... -</server> -... -- -
The JMX remote url of the cluster daemon adheres to the following syntax:
- service:jmx:rmi://host/jndi/rmi://host:port/protocolconnector_name
- with the following meanings:
host: ip alias or ip address of the machine that hosts the cluster daemon
- (by default localhost, can be overridden through the carol.properties file)
- port: tcp listen port of the registry embedded in the cluster daemon
- (by default 1806, can be overridden through the carol.properties file)
- protocol: protocol used for accessing the JMX interface (by default irmi, can be overridden
- through the carol.properties file)name: cluster daemon instance name (defined in the clusterd.xml file)The cluster daemon is started using the command jclusterd. The possible options are:
| option | -description | -
|---|---|
| start | -Start the cluster daemon. - | -
| stop | -Stop the cluster daemon. - | -
| -DdomainName | -Domain name to use for starting the JOnAS instance. This value is used when it is defined both here and in the clusterd.xml file. - | -
| -carolFile <my-carol.properties> | -Path to the carol.properties file to use. If not specified, the file is loaded from $JONAS_BASE/conf. - If the file is not found, the default values (localhost, 1806, irmi) are used. | -
| -confFile <my-clusterd.xml> | -Path to the clusterd.xml file to load. If not specified, the file is loaded from $JONAS_BASE/conf. | -
The cluster daemon provides a JMX interface that enables control of the JOnAS instances. The following operations are -available:
- - - -| Operation | -Description | -
|---|---|
| String getServersList() | -Return the list of JOnAS instances | -
| int pingJOnAS(String name) | -Ping a JOnAS instance identified by its name | -
| void startJOnAS(String name) | -Start a JOnAS instance identified by its name | -
| String startAllJOnAS(String domainName, String prm) | -Start all the JOnAS instances known in the cluster daemon configuration.
- The parameter domainName (optional) enables the ability to specifiy the domain name.
- The parameter prm (optional) enables the ability to set some JVM parameters.
- |
-
| void stopJOnAS(String name) | -Stop a JOnAS instance identified by its name | -
| String stopAllJOnAS() | -Stop all the JOnAS instances known in the cluster daemon configuration | -
| String getJavaHome4Server(String name) | -Get the JAVA_HOME defined for a JOnAS server | -
| String getJonasRoot4Server(String name) | -Get the JONAS_ROOT defined for a JOnAS server | -
| String getJonasBase4Server(String name) | -Get the JONAS_BASE defined for a JOnAS server | -
| void reloadConfiguration() | -Reload the configuration file of the cluster daemon | -
| void addServer(String name, String description, String javaHome, String jonasRoot, String jonasBase) | -Add a definition of a JOnAS instance to the cluster daemon configuration. The change is saved in the - configuration file. | -
| void removeServer(String name) | -Remove a definition of a JOnAS instance in the cluster daemon configuration. The change is saved in the - configuration file. | -
| void modifyServer(String name, String description, String javaHome, String jonasRoot, String jonasBase) | -Modify the definition of a JOnAS instance in the cluster daemon configuration. The change is saved in the - configuration file. | -
JOnAS provides a full solution for clustering that ensures high availability and -scalability of J2EE applications.
-The Howto document JOnAS clustering -is a guide for configuring the clustering features of JOnAS.
- -Cluster management is described in Domain and Cluster Management in -JOnAS chapter.
- -
-Authors : Georges Goebel, Marc Calvisi, Rod Schultz, Jerome Pioux, Benoit Pelletier
-October 16, 2006
-Version : 3.2
-
- - - -
-Load balancing at web level with -mod_jk
--Session Replication at web level
- --Session Replication at EJB level
--Clustering databases with -C-JDBC
-SampleCluster2 Practical Example
- --Installing Java, Ant and JOnAS / Tomcat
- - - - - - - - - - - --Description of the sampleCluster2 Web -Interface
- -This guide describes how to configure Apache, Tomcat, and JOnAS -to install a cluster.
-Clustering with JOnAS uses the following:
-This document describes one architecture with all the clustering -functionalities available in JOnAS, the configuration of -architectures integrating one of those functionalities, and other -possible configurations.
-For hands-on practice, this document uses the sampleCluster2 -JOnAS example.
-- -
The architecture shown in the following illustration provides -all the clustering functionality available in JOnAS: 1) Apache as the -front-end HTTP server, 2) JOnAS/Tomcat as the J2EE Container, and 3) a shared database.
-This architecture provides:
-
- At the Servlet / JSP level, the mod_jk plug-in
-provides Load Balancing / High Availability and the
-Tomcat-Replication module provides Failover.
- At the EJB level, the CMI protocol and JNDI replication provides Load Balancing / High Availability.
-Replication of Stateful EJBs provides failover.
- The database is shared by the JOnAS servers.
The sampleCluster2 application, presented later in this document, can be deployed on such an architecture.
-|
-
|
-
- A node (computer) that hosts one or more servers |
-
-
|
-
-
|
|
-
|
-
- A web container |
-
-
|
-
- An ejb container |
|
-
|
-
- A JOnAS instance that hosts a web container |
-
-
|
-
- A JOnAS instance that hosts an ejb container |
|
-
|
-
- A JOnAS instance that hosts a web container and an ejb -container |
-
-
|
-
-
|
|
-
|
-
- An Apache server with the mod_jk module |
-
-
|
-
- - -
|
The following illustration describes how Apache, mod_jk, and -JOnAS/Tomcat Containers interact:
-This example uses mod_jk, but an alternative configuration -using Enhydra Director -is also possible. (see -config)
-Mod_jk is a plug-in (module) that handles the communication and -load balancing between Apache and Tomcat.
-Mod_jk uses the concept of worker. A worker is a Tomcat instance -that is running to perform servlet requests coming from the web -server. Each worker is identified to the web server by the host on -which it is located, the port where it listens, and the -communication protocol that is used to exchange messages.
-AJP13 is the preferred TCP/IP sockets protocol that mod_jk uses -for communicating between the web server and Tomcat workers.
-In this configuration there is one worker for each Tomcat -instance and one worker (this -is a specific worker with no host and no port number) that will handle the load balancing. -All workers -are defined in a file called worker.properties.
-Note: this module can also be used for site partitioning.
-- -
The following illustration shows that the HTTP session replication -feature has been added to the architecture:
-
The term "session replication" is used when the current service -state is being replicated across multiple application instances. Session replication occurs when the information stored in an -HttpSession is replicated from, in this example, one servlet engine -instance to another. This could be almost any type of data, such as items contained in -a shopping cart or information being entered on an insurance -application. Anything being stored in the session must be -replicated for the service to failover without a disruption.
-The solution chosen for achieving Session replication is called -all-to-all replication. Tomcat uses a proprietary protocol based on -TCP for the all-to-all replication.
-- -
The following illustration shows that load balancing at EJB -level is now included in the architecture:
-
CMI is a new ORB used by JOnAS to provide clustering for load -balancing and high availability. It provides replication of the -JNDI registries among all EJB containers. Several instances of -JOnAS can be started together in a cluster to share their EJBs. It -is possible to start the same EJB on each JOnAS, or to distribute -their load. A URL referencing several JOnAS instances can be -provided to the clients. At lookup time, a client randomly chooses -one of the available servers to request the required bean. Each -JOnAS instance has the knowledge (through JGroups) of the -distribution of the Beans in the cluster. An answer to a lookup is -a special clustered stub, containing stubs to each instance known -in the cluster. Each method call on the Home (or Remote for the SSB) -of the bean can be issued by the stub to a new instance in order to balance the load on the -cluster. The default algorithm used for load distribution is -currently a weighted round robin with local preference.
- -The following illustration shows that the EJB session replication -feature has been added to the architecture:
-
The term "session replication" is used when the current service -state is being replicated across multiple application instances. -Session replication occurs when the information stored in an SFSB state -is replicated from, in this example, one EJB container -instance to another. This could be almost any type of data (that is serializable), -such as items contained in -a shopping cart or information being entered on an insurance -application. Anything being stored in the session must be -replicated for the service to failover without a disruption.
-The solution chosen for achieving Session replication is based on a horizontal -approach implemented both through CMI and the JOnAS's ha service. -See here for more detailed information
- -With C-JDBC it is possible to cluster databases. Refer to - -HowTo setup a C-JDBC Database.
-- -
sampleCluster2 is an application that demonstrates the clustering features. -A jsp/servlet follows the requests movements across the cluster. -As shown in the illustration below, it can be deployed over four -JOnAS instances. Two -have WEB containers and the other two have EJB containers.
-
The application is composed of three EJBs: a stateful session bean, a stateless -session bean, and an entity bean. These EJBs are instantiated by the web interface. -When the user connects to the web interface for the first time, an HTTP session is created. -During this process a -stateful session bean is created in one of the JOnAS nodes where -the EJB container is started. The handle of this stateful session -bean is added to the HTTP session (see note). Next, the web -interface creates a new instance of the stateless session bean. The -first time, no entity bean is created. The useful information from -the stateless session bean (JOnAS node name, number of instances) -is set in the stateful session bean.
-The user can see the result in the web interface where all the -necessary information is displayed. The user should now execute the -same servlet several times in order to see the changes made by the -cluster. Each time the servlet is executed, it may be -executed on a different node (JOnAS with web container).
-The servlet gets a reference to the stateful session bean -(through the handle). After that, a new stateless session bean is -created and its information is passed to the stateful session bean. On -every tenth instantiation of the stateless session bean, an entity bean is created.
-However, the stateless session bean may be instantiated in a -different EJB container than the stateful session bean. This -sample uses local interfaces between the stateless session bean -and the entity bean. As a result, the entity bean is created in the -same EJB container as the stateless session bean.
-The entity bean writes the time and the name of the node in the -database.
-Note: The handle enables getting a reference to the stateful session bean -when the JVM has changed.
-See also description of the -SampleCluster2 Web interface for a description of using sampleCluster2 to -demonstrate cluster features.
-- -
This section provides information about installing JOnAS /Tomcat, Apache, mod_jk.
-The versions assumed here are: JOnAS 4.8.x /Tomcat 5.5.x, Apache -2.2.x, and mod_jk 1.2.15 (or later).
-Perform steps one through three in -Installing JOnAS with a web container from scratch.
-Linux Notes:
-export JAVA_HOME=<location where java was installed>
-export ANT_HOME=<location where ant was installed>
-export JONAS_ROOT=$HOME/cluster/JONAS_4_8_3
-export PATH=$PATH:$JAVA_HOME/bin:$ANT_HOME/bin
-Windows Notes:
-JAVA_HOME <location where java was -installed>
-ANT_HOME <location where ant was -installed>
--JONAS_ROOT -c:\cluster\JONAS_4_8_3
-Add to PATH ;$JAVA_HOME/bin;$ANT_HOME/bin
--
For this sample, Apache will run as <user> (rather than
-'root').
-Below, <prefix> refers to the install folder for Apache.
-This sample uses prefix = $APACHE_HOME=
-$HOME/cluster/apache2.
Run and Stop Apache HTTP server to verify the installation.
-Notes:
-Run and Stop Apache HTTP server:
-For further information about installing Apache HTTP server -please refer to the Apache -Site.
-- -
Mod_jk will be installed in the same <user> account as -Apache.
- -A mod_jk.so file should now have been created under $APACHE_HOME/modules.
-The process for making apache aware of this new file will be performed in the
-next chapter.
-
-Note: For some distributions, a binary version may be
-available at the Tomcat site.
For further installation information, refer to the -Tomcat -Site.
-For further - installation information, refer to the Tomcat - Site.
-- -
-The localhost must be mapped to a non lookback IP by editing the hosts file: either /etc/hosts in a linux system or c:/Windows/system32/etc/hosts for -the Windows OS. -
-Note: A WebApp deployed into a Cluster must have a
-special distributable element set in its WEB-INF/web.xml.
-The following is an example of a web.xml deployment descriptor:
-
<web-app . . .>
- . . .
- <distributable />
- . . .
-</web-app>
Please carefully read the - -Tomcat Clustering Guide for additional information.
- -Note: For sampleCluster2, in the JOnAS-specific deployment -descriptor, tag shared is set to true for the entity beans involved. When this flag is set to true, multiple instances of the same -entity bean in different JOnAS servers can access a common database -concurrently.
-The following is an example of a deployment descriptor generated by newjc with the -flag shared set to true. Deployment descriptors are in jonas_ejb_jar.xml in the ejbs.jar file in sampleCluster2.ear.
-<jonas-ejb-jar>
- <jonas-entity>
- .
-. .
-<shared>true</shared>
- .
-. .
</jonas-entity>
-</jonas-ejb-jar>
- - -
sampleCluster2 is located under -$JONAS_ROOT/examples/sampleCluster2.
-/lib libraries needed by the aplication -to run
-/output generated ear, jar, war files
-/src source code
- -Note: sampleCluster2 contains both a war file for the web -application and a jar file for the EJB. JOnAS will only deploy the -war file to instances with a web container. Similarly, it will only -deploy the jar file on instances with an EJB container.
-- -
The following graphic shows an example "SessionServlet Output" page.
- --
-
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
The following is an explanation of the information shown in the "SessionServlet -Output" page above.
-Home of sampleCluster2
-After click on open session link
-After click on check session link
-By default, the RMI protocol in JOnAS uses a random port at each startup, -which implies that there is no way to configure a firewall as the port number -changes each time the system restarts. -
- -However, as of JOnAS version 4.4.1, you can easily configure the RMI port number
-by setting only one property per protocol in the
-$JONAS_BASE/conf/carol.properties file.
-
To configure the RMI exported-port number, edit the
-$JONAS_BASE/conf/carol.properties file
-to change the following protocols from 0 (choose a random port number) to the
-port number you want:
-
-carol.jrmp.server.port=0 --
-carol.jeremie.server.port=0 --
-carol.iiop.server.port=0 --
Note:
-The jonas.orb.port property has been moved from the
-$JONAS_BASE/conf/jonas.properties file to the
-$JONAS_BASE/conf/carol.properties file, as the latter is the file
-in which the registry ports and protocols were already being set.
-In previous JOnAS versions the jonas.orb.port property
-was not useful in multi-protocols mode as it allowed only one port number
-to be set for a single protocol.
-Also, the jonas.orb.port property was working only for RMI/JRMP
-and for objects using the PortableRemoteObject class for their export.
-
-Authors : Yannick Braeuner, Benoit Pelletier
-February 12, 2008
-Version : 2.0
-
-JORAM distributed configuration
- - - - - - - --First scenario for Queue : distribution of the load at the server side
- --Second scenario for Queue : load-balancing at the client side
- - - - - -The JMS API provides a separate domain for each messaging approach, point-to-point or -publish/subscribe. The point-to-point domain is built around the concept of queues, senders and receivers. -The publish/subscribe domain is built around the concept of topic, publisher and subscriber. -Additionally it provides a unified domain with common interfaces that enable the use of queue and topic. -This domain defines the concept of producers and consumers. -The classic sample uses a very simple configuration (centralized) made of one server hosting a queue and a topic. -The server is administratively configured for accepting connection requests from the anonymous user. -
-JMS clustering aims to offer a solution for both the scalability and the high availability for the JMS accesses. -This document gives an overview of the JORAM capabilities for clustering a JMS application in the J2EE context. -The load-balancing and fail-over mechanisms are described and a user guide describing how to build such a configuration -is provided. Further information is available in the JORAM documentation here.
- -The following information will be presented:
-Getting started :
-Two instances of JOnAS are configured ("J1" and "J2"). Each JOnAS instance has a dedicated collocated JORAM server: server - "S1" for JOnAS "J1", "S2" for "J2". Those two servers are aware of each other.
- -Set a JORAM distributed configuration:
- --<?xml version="1.0"?> -<config - <domain name="D1"/> - <property name="Transaction" value="fr.dyade.aaa.util.NTransaction"/> - <server id="1" name="S1" hostname="localhost"> - <network domain="D1" port="16301"/> - <service class="org.objectweb.joram.mom.proxies.ConnectionManager" - args="root root"/> - <service class="org.objectweb.joram.mom.proxies.tcp.TcpProxyService" - args="16010"/> - </server> - <server id="2" name="S2" hostname="localhost"> - <network domain="D1" port="16302"/> - <service class="org.objectweb.joram.mom.proxies.ConnectionManager" - args="root root"/> - <service class="org.objectweb.joram.mom.proxies.tcp.TcpProxyService" - args="16020"/> - </server> -</config> --
- <config-property> - <config-property-name>ServerId</config-property-name> - <config-property-type>java.lang.Short</config-property-type> - <config-property-value>1</config-property-value> - </config-property> --
- <config-property> - <config-property-name>ServerName</config-property-name> - <config-property-type>java.lang.String</config-property-type> - <config-property-value>s1</config-property-value> - </config-property> --
- <config-property> - <config-property-name>HostName</config-property-name> - <config-property-type>java.lang.String</config-property-type> - <config-property-value>localhost</config-property-value> - </config-property> --
- <config-property> - <config-property-name>ServerPort</config-property-name> - <config-property-type>java.lang.Integer</config-property-type> - <config-property-value>16010</config-property-value> - </config-property> --
- <config-property> - <config-property-name>PersistentPlatform</config-property-name> - <config-property-type>java.lang.Boolean</config-property-type> - <config-property-value>true</config-property-value> - </config-property> --
- <User name="anonymous" - password="anonymous" - serverId="1"/> --
- <ConnectionFactory className="org.objectweb.joram.client.jms.tcp.TcpConnectionFactory"> - <tcp host="localhost" - port="16010"/> - <jndi name="JCF"/> - </ConnectionFactory> - - <ConnectionFactory className="org.objectweb.joram.client.jms.tcp.QueueTcpConnectionFactory"> - <tcp host="localhost" - port="16010"/> - <jndi name="JQCF"/> - </ConnectionFactory> - - <ConnectionFactory className="org.objectweb.joram.client.jms.tcp.TopicTcpConnectionFactory"> - <tcp host="localhost" - port="16010"/> - <jndi name="JTCF"/> - </ConnectionFactory> --
See here for more information about a JORAM distributed configuration.
- -A non hierarchical topic might also be distributed among many servers. Such a topic, to be -considered as a single logical topic, is made of topic representatives, one per server. Such an architecture allows a publisher to publish messages on a representative of the topic. In the example, the publisher works with the representative on server 1. If a subscriber subscribed to any other representative (on server 2 in the example), it will get the messages produced by the publisher.
- -Load balancing of topics is very useful because it allows distributed topic subscriptions across the cluster.
- -
The following scenario and general settings are proposed:
-
-The cluster definition with the topics must be added in $JONAS_BASE/conf/joramAdmin.xml file. -The connection factories and the anonymous user must be defined with the local server id and the local server port number -according to the a3servers.xml content. Here only the cluster related elements are shown: -
- -- <Topic name="mdbTopic1" serverId="1"> - <freeReader/> - <freeWriter/> - <jndi name="mdbTopic"/> - </Topic> - - <Topic name="mdbTopic2" serverId="2"> - <freeReader/> - <freeWriter/> - <jndi name="mdbTopic2"/> - </Topic> - - <ClusterTopic> - <ClusterElement name="mdbTopic1" location="s1"/> - <ClusterElement name="mdbTopic2" location="s2"/> - <jndi name="clusterMdbTopic"/> - </ClusterTopic> --
- <Topic name="mdbTopic1" serverId="1"> - <freeReader/> - <freeWriter/> - <jndi name="mdbTopic1"/> - </Topic> - - <Topic name="mdbTopic2" serverId="2"> - <freeReader/> - <freeWriter/> - <jndi name="mdbTopic"/> - </Topic> - - <ClusterTopic> - <ClusterElement name="mdbTopic1" location="s1"/> - <ClusterElement name="mdbTopic2" location="s2"/> - <jndi name="clusterMdbTopic"/> - </ClusterTopic> --
The joramAdmin.xml file has to be loaded when all cluster members are started since some remote - cluster elements are defined. An alternative consists in splitting the configuration into two different files - joramAdmin-local.xml and joramAdmin-cluster.xml, the first one containing only the local elements and the - second one, both local and remote elements. At the JOnAS starting, a script could copy the right file - to joramAdmin.xml according to the others members presence (joramAdmin-local.xml if it's the first member - which starts and joramAdmin-cluster.xml if all the cluster members are started).
- -Deploy the application, for example, create a deploy.sh file:
--#!/bin/ksh - -export JONAS_BASE=$PWD/jb1 -cp $JONAS_ROOT/examples/output/ejbjars/newsamplemdb.jar $JONAS_BASE/ejbjars/ -jonas admin -a newsamplemdb.jar -n node1 - -export JONAS_BASE=$PWD/jb2 -cp $JONAS_ROOT/examples/output/ejbjars/newsamplemdb.jar $JONAS_BASE/ejbjars/ -jonas admin -a newsamplemdb.jar -n node2 -- -
jclient newsamplemdb.MdbClient- -
Something similar to this should appear in the client console :
--ClientContainer.info : Starting client... -JMS client: tcf = TCF:localhost-16010 -JMS client: topic = topic#1.1.1026 -JMS client: tc = Cnx:#0.0.1026:5 -MDBsample is Ok -- -
In addition, the following should appear on each JOnAS instance console:
- --Message received: Message6 -MdbBean onMessage -Message received: Message7 -MdbBean onMessage -Message received: Message8 -- -
The fact that each message appears on the two different JOnAS servers consoles shows the messages broadcasting between the -topic elements.
- -Globally, the load balancing in the context of queues may be meaningless in comparison of load balancing topic. -It would be a bit like load balancing a stateful session bean instance (which just requires failover). -But the JORAM distributed architecture enables :
-Here is a diagram of what is going to happen for the Queue and the message:
- -
A load balancing message queue may be needed for a high rate of messages. -A clustered queue is a cluster of queues exchanging messages depending on their load. The example has a cluster of two queues. -A heavy producer accesses its local queue and sends messages. It quickly becomes loaded and decides to forward messages to the other queue of its cluster which is not under heavy load.
- -For this case some parameters must be set:
-For further information, see the JORAM documentation here.
- -The scenario for Queue is similar to the topic one. A client sent messages to a queue in S1. MDB gets messages -from each local cluster queue representative. After having sent a burst of messages to the server S1, -the load distribution should occur and message should be moved to S2.
- - -The Queue definition in $JONAS_BASE/conf/joramAdmin.xml file is as following :
- --<Queue name="mdbQueue1" - serverId="1" - className="org.objectweb.joram.mom.dest.ClusterQueue"> - <freeReader/> - <freeWriter/> - <property name="period" value="10000"/> - <property name="producThreshold" value="50"/> - <property name="consumThreshold" value="2"/> - <property name="autoEvalThreshold" value="false"/> - <property name="waitAfterClusterReq" value="1000"/> - <jndi name="mdbQueue"/> -</Queue> - -<Queue name="mdbQueue2" - serverId="2" - className="org.objectweb.joram.mom.dest.ClusterQueue"> - <freeReader/> - <freeWriter/> - <property name="period" value="10000"/> - <property name="producThreshold" value="50"/> - <property name="consumThreshold" value="2"/> - <property name="autoEvalThreshold" value="false"/> - <property name="waitAfterClusterReq" value="1000"/> - <jndi name="mdbQueue2"/> - -<ClusterQueue> - <ClusterElement name="mdbQueue1" location="s1"/> - <ClusterElement name="mdbQueue2" location="s2"/> - <jndi name="mdbQueueCluster"/> -</ClusterQueue> - -- -
-<Queue name="mdbQueue1" - serverId="1" - className="org.objectweb.joram.mom.dest.ClusterQueue"> - <freeReader/> - <freeWriter/> - <property name="period" value="10000"/> - <property name="producThreshold" value="50"/> - <property name="consumThreshold" value="2"/> - <property name="autoEvalThreshold" value="false"/> - <property name="waitAfterClusterReq" value="1000"/> - <jndi name="mdbQueue1"/> -</Queue> - -<Queue name="mdbQueue2" - serverId="2" - className="org.objectweb.joram.mom.dest.ClusterQueue"> - <freeReader/> - <freeWriter/> - <property name="period" value="10000"/> - <property name="producThreshold" value="50"/> - <property name="consumThreshold" value="2"/> - <property name="autoEvalThreshold" value="false"/> - <property name="waitAfterClusterReq" value="1000"/> - <jndi name="mdbQueue"/> - -<ClusterQueue> - <ClusterElement name="mdbQueue1" location="s1"/> - <ClusterElement name="mdbQueue2" location="s2"/> - <jndi name="mdbQueueCluster"/> -</ClusterQueue> -- - -
Run the sample
- -The procedure is similar to the topic example described above, just use the newsamplemdb2 example rather than -newsample one.
- -The load-balancing is done at the client side. A server is selected randomly among the cluster members -at the first message sending or through the 'location' java property. And then, for a given client, all the messages -are sent to the same server unless the java property resetting.
- -
For setting the load-balancing at the client side, the client application must use a clustered connection factory that -embeds the network connection parameters of the cluster members. This factory must be registered in the JORAM's -distributed JNDI for ensuring that the client gets an up to date object. A complete description of the -JORAM JNDI setting is given here and the main parameters -are given below :
- -At first, the a3servers.xml file must enhanced with the JORAM's jndi service as following :
- --<?xml version="1.0"?> -<config> - <domain name="D1"/> - <property name="Transaction" value="fr.dyade.aaa.util.NTransaction"/> - - <server id="1" name="s1" hostname="localhost"> - <network domain="D1" port="16301"/> - <service class="org.objectweb.joram.mom.proxies.ConnectionManager" - args="root root"/> - <service class="org.objectweb.joram.mom.proxies.tcp.TcpProxyService" - args="16010"/> - <service class="fr.dyade.aaa.jndi2.distributed.DistributedJndiServer" - args="16401 0 1"/> - </server> - - <server id="2" name="s2" hostname="localhost"> - <network domain="D1" port="16302"/> - <service class="org.objectweb.joram.mom.proxies.ConnectionManager" - args="root root"/> - <service class="org.objectweb.joram.mom.proxies.tcp.TcpProxyService" - args="16020"/> - <service class="fr.dyade.aaa.jndi2.distributed.DistributedJndiServer" - args="16402 1 0"/> - </server> - -</config> -- -
Only the JMS objects must be registered in the JORAM's jndi. The standard routing mechanism is used through a jndi.properties file -put in each $JONAS_BASE/conf directory :
- -- java.naming.factory.url.pkgs org.objectweb.jonas.naming:fr.dyade.aaa.jndi2 - scn.naming.factory.host localhost - scn.naming.factory.port 16402 -- - -
The port number must be adapted according to the local server configuration (16401 for S1 and 16402 for S2). The 'scn' prefix -is defined for identifying the objects to bind or to lookup in this registry.
- -The clustered connection factories are defined in the $JONAS_BASE/conf/joramAdmin.xml file as following :
- --<ConnectionFactory name="JQCF1" className="org.objectweb.joram.client.jms.tcp.QueueTcpConnectionFactory"> - <tcp host="localhost" - port="16010"/> - <jndi name="scn:comp/JQCF1"/> -</ConnectionFactory> -<ConnectionFactory name="JQCF2" className="org.objectweb.joram.client.jms.tcp.QueueTcpConnectionFactory"> - <tcp host="localhost" - port="16020"/> - <jndi name="scn:comp/JQCF2"/> -</ConnectionFactory> -<ClusterCF> - <ClusterElement name="JQCF1" location="s1"/> - <ClusterElement name="JQCF2" location="s2"/> - <jndi name="scn:comp/clusterJQCF"/> -</ClusterCF> -- -
The 'scn:comp/' prefix in the jndi name indicates that the object must be bound in the JORAM's jndi.
- -The cluster queue is defined in the $JONAS_BASE/conf/joramAdmin.xml file :
- --<Queue name="mdbQueue0" serverId="1" - className="org.objectweb.joram.mom.dest.ClusterQueue"> - <freeReader/> - <freeWriter/> - <jndi name="scn:comp/mdbQueue1"/> -</Queue> - -<Queue name="mdbQueue1" serverId="2" - className="org.objectweb.joram.mom.dest.ClusterQueue"> - <freeReader/> - <freeWriter/> - <jndi name="scn:comp/mdbQueue2"/> -</Queue> - -<ClusterQueue> - <ClusterElement name="mdbQueue1" location="s1"/> - <ClusterElement name="mdbQueue2" location="s2"/> - <jndi name="scn:comp/mdbQueue"/> -</ClusterQueue> -- -
Note that the cluster queue definition is symetric accross the cluster members. The well known jndi name is set -on the cluster object (and not in the local representative as for the topic cluster).
- -Note that same for the topic declaration, the joramAdmin.xml file has to be loaded when all cluster members - are started since some remote cluster elements are defined. - An alternative consists in splitting the configuration into two different files - joramAdmin-local.xml and joramAdmin-cluster.xml, the first one containing only the local elements and the - second one, both local and remote elements. At the JOnAS starting, a script could copy the right file - to joramAdmin.xml according to the others members presence (joramAdmin-local.xml if it's the first member - which starts and joramAdmin-cluster.xml if all the cluster members are started).
- -The message driven bean must be configured with the queue registered in the JORAM jndi ('scn:/comp' selector). - Edit the deployment descriptor file (ejb-jar.xml) :
- -- <message-driven> - <description>Describe here the message driven bean Mdb</description> - <display-name>Message Driven Bean Mdb</display-name> - <ejb-name>Mdb</ejb-name> - <ejb-class>newsamplemdb2.MdbBean</ejb-class> - <messaging-type>javax.jms.MessageListener</messaging-type> - <transaction-type>Container</transaction-type> - <message-destination-type>javax.jms.Queue</message-destination-type> - <activation-config> - <activation-config-property> - <activation-config-property-name>destination</activation-config-property-name> - <activation-config-property-value>scn:comp/mdbQueue</activation-config-property-value> - </activation-config-property> - <activation-config-property> - <activation-config-property-name>destinationType</activation-config-property-name> - <activation-config-property-value>javax.jms.Queue</activation-config-property-value> - </activation-config-property> - <activation-config-property> - <activation-config-property-name>subscriptionDurability</activation-config-property-name> - <activation-config-property-value>NonDurable</activation-config-property-value> - </activation-config-property> - </activation-config> - </message-driven> -- -
The client must lookup the clustered objects in the JORAM's jndi by using the 'scn:/comp' selector.
- --static String queueName = "scn:comp/mdbQueue"; -static String conFactName = "scn:comp/clusterJQCF"; -Context ictx = new InitialContext(); -ConnectionFactory qcf = (ConnectionFactory) ictx.lookup(conFactName ); -Queue queue = (Queue) ictx.lookup(queueName); -- -
The connection creation, session creation and producer are quite classic:
--Connection qc = qcf.createConnection(); -Session session = qc.createSession(false, Session.AUTO_ACKNOWLEDGE); -MessageProducer qp = session.createProducer(queue); -- -
A server is chosen at the first message sending. A switch may be forced through the resetting of the 'location' java -property. Below a new server election is requested for each odd iteration.
- -![node](-"images/clusterfiles/Node.jpg")
![WebCont](-"images/clusterfiles/WebCont.jpg")
![EJBCont](-"images/clusterfiles/EJBCont.jpg")
![JOnASWeb](-"images/clusterfiles/JOnASWeb.jpg")
![JOnASEJB](-"images/clusterfiles/JOnASEJB.jpg")
![FullJOnAS](-"images/clusterfiles/FullJOnAS.jpg")
![Apache](-"images/clusterfiles/Apache.jpg")
-TextMessage message;
-for (int i = 0; i < 10; i++) {
- message = session.createTextMessage();
- message.setText("Msg "+i);
- qp.send(message);
- System.out.println("location=" + System.getProperty("location"));
- if (i%2 == 0) {
- System.setProperty("location", "");
- }
-}
-
-
-The procedure is similar to the topic and queue ones described above, just adapt the newsamplemdb2 example with -the configuration and code given previously.
- - -
An HA server is actually a group of servers, one of which is the master server that coordinates the other slave servers. An external server that communicates with the HA server is actually connected to the master server.
-Each replicated JORAM server executes the same code as a standard server except for the communication with the clients.
-In the example, the collocated clients use a client module (newsamplemdb). If the server replica is the master, then the connection is active enabling the client to use the HA JORAM server. If the replica is a slave, then the connection opening is blocked until the replica becomes the master.
- -Several files must be changed to create a JORAM HA configuration:
- -A clustered server is defined by the element "cluster". A cluster owns an identifier and a name defined by the attributes "id" and "name" (exactly like a standard server). Two properties must be defined:
-In the case of one server and one replica, the value must be set to 1.
--<?xml version="1.0"?/> -<config> - <domain name="D1"/> - - <property name="Transaction" value="fr.dyade.aaa.util.NullTransaction"/> - - <cluster id="0" name="s0"> - - <property name="Engine" value="fr.dyade.aaa.agent.HAEngine" /> - <property name="nbClusterExpected" value="1" /> -- -
For each replica, an element "server" must be added. The attribute "id" defines the identifier of the replica inside the cluster. The attribute "hostname" gives the address of the host where the replica is running. The network is used by the replica to communicate with external agent servers, i.e., servers located outside of the cluster and not replicas.
- -This is the entire configuration for the a3servers.xml file of the first JOnAS instance jb1:
- --<?xml version="1.0"?> -<config< - <domain name="D1"/> - - <property name="Transaction" value="fr.dyade.aaa.util.NullTransaction"/> - - <cluster id="0" name="s0"> - - <property name="Engine" value="fr.dyade.aaa.agent.HAEngine" /> - <property name="nbClusterExpected" value="1" /> - - <server id="1" hostname="localhost"> - <network domain="D1" port="16300"/> - <service class="org.objectweb.joram.mom.proxies.ConnectionManager" args="root root"/> - <service class="org.objectweb.joram.mom.proxies.tcp.TcpProxyService" args="16010"/> - <service class="org.objectweb.joram.client.jms.ha.local.HALocalConnection"/> - </server> - - <server id="2" hostname="localhost"> - <network domain="D1" port="16301"/> - <service class="org.objectweb.joram.mom.proxies.ConnectionManager" args="root root"/> - <service class="org.objectweb.joram.mom.proxies.tcp.TcpProxyService" args="16020"/> - <service class="org.objectweb.joram.client.jms.ha.local.HALocalConnection"/> - </server> - - </cluster> - -</config> -- -
The cluster id = 0 and the name S0. It is exactly the same file for the second instance of JOnAS.
- -Here is the joramAdmin.xml file configuration:
- --<?xml version="1.0"?> - -<JoramAdmin> - -<AdminModule> - <collocatedConnect name="root" password="root"/> -</AdminModule> - -<ConnectionFactory className="org.objectweb.joram.client.jms.ha.tcp.HATcpConnectionFactory"> - <hatcp url="hajoram://localhost:16010,localhost:16020" reliableClass="org.objectweb.joram.client.jms.tcp.ReliableTcpClient"/> - <jndi name="JCF"/> -</ConnectionFactory> - -<ConnectionFactory className="org.objectweb.joram.client.jms.ha.tcp.QueueHATcpConnectionFactory"> - <hatcp url="hajoram://localhost:16010,localhost:16020" reliableClass="org.objectweb.joram.client.jms.tcp.ReliableTcpClient"/> - <jndi name="JQCF"/> -</ConnectionFactory> - -<ConnectionFactory className="org.objectweb.joram.client.jms.ha.tcp.TopicHATcpConnectionFactory"> - <hatcp url="hajoram://localhost:16010,localhost:16020" reliableClass="org.objectweb.joram.client.jms.tcp.ReliableTcpClient"/> - <jndi name="JTCF"/> -</ConnectionFactory> -- -
Each connection factory has its own specification. One is in case of the Queue, one for Topic, and one for no define arguments. Each time the hatcp url must be entered, the url of the two instances. In the example, it is localhost:16010 and localhost:16020. It allows the client to change the instance when the first one is dead.
-After this definition the user, the queue and topic can be created.
- -First, in order to recognize the cluster, a new parameter must be declared in these files.
-- <config-property> - <config-property-name>ClusterId</config-property-name> - <config-property-type>java.lang.Short</config-property-type> - <config-property-value>0</config-property-value> - </config-property> --
Here the name is not really appropriate but in order to keep some coherence this name was used. In fact it represents a replica so it would have been better to call it replicaId.
- -Consequently, for the first JOnAS instance, copy the code just above. For the second instance, change the value to 1 (in order to signify this is another replica).
- -First launch the two JOnAS bases. Create a runHa.sh file in which the following code will be added:
--export JONAS_BASE=$PWD/jb1 -export CATALINA_BASE=$JONAS_BASE -rm -f $JONAS_BASE/logs/* -jonas start -win -n node1 -Ddomain.name=HA --
Then do the same for the second JOnAS base. After that launch the script.
-One of the two JOnAS bases (the one which is the slowest) will be in a waiting state when reading the joramAdmin.xml
--JoramAdapter.start : - Collocated JORAM server has successfully started. -JoramAdapter.start : - Reading the provided admin file: joramAdmin.xml --
whereas the other one is launched successfully.
-Then launch (through a script or not) the newsamplemdb example:
--jclient -cp /JONAS_BASE/jb1/ejbjars/newsamplemdb.jar:/JONAS_ROOT/examples/classes -carolFile clientConfig/carol.properties newsamplemdb.MdbClient --
Messages are sent on the JOnAS base which was launched before. Launch it again and kill the current JOnAS. The second JOnAS will automatically wake up and take care of the other messages.
- - -This is a proposal for building an MDB clustering based application.
- -This is like contested Queues. i.e., there is more than one receiver on different machines receiving from the queue. This load balances the work done by the queue receiver, not the queue itself.
- -The HA mechanism can be mixed with the load balancing policy based on clustered destinations. The load is balanced between several HA servers. Each element of a clustered destination is deployed on a separate HA server.
- -
Here is the supposed configuration (supposed because it has not been verifed).
- -
The configuration must now be tested, as follows: -
JOnAS release 4.1 dramatically simplifies the use of a distributed JORAM -platform from within JOnAS servers. For example, such a configuration allows -a bean hosted by JOnAS instance "A" to send messages on a JORAM queue, to -which a MDB hosted by JOnAS instance "B" listens.
- -This advancement is due to the following:
-Before going through this chapter, it is highly recommended that the JORAM Resource Adapter -configuration guide be reviewed.
- -The following scenario and general settings are proposed:
-The JORAM servers are part of the same JORAM platform described by the
-following a3servers.xml configuration file:
<?xml version="1.0"?> -<config> - <domain name="D1"/> - <server id="0" name="S0" hostname="hostA"> - <network domain="D1" port="16301"/> - <service class="org.objectweb.joram.mom.proxies.ConnectionManager" - args="root root"/> - <service class="org.objectweb.joram.mom.proxies.tcp.TcpProxyService" - args="16010"/> - <service class="fr.dyade.aaa.jndi2.distributed.DistributedJndiServer" - args="16400 0"/> - </server> - <server id="1" name="S1" hostname="hostB"> - <network domain="D1" port="16301"/> - <service class="org.objectweb.joram.mom.proxies.ConnectionManager" - args="root root"/> - <service class="org.objectweb.joram.mom.proxies.tcp.TcpProxyService" - args="16010"/> - <service class="fr.dyade.aaa.jndi2.distributed.DistributedJndiServer" - args="16400 0 1"/> - - </server> -</config>- -
This configuration describes a platform made up of two servers, "s0" and -"s1", hosted by machines "hostA" and "hostB", listening on ports 16010, -providing a distributed JNDI service (more info on JORAM's JNDI may be found -here).
- -Each JOnAS server must hold a copy of this file in its conf/
-directory. In its jonas.properties file, each must declare the
-joram_for_jonas_ra.rar as a resource to be deployed (and each
-should remove jms from its list of services).
JOnAS A embeds JORAM server s0. The
-jonas-ra.xml descriptor packaged in the
-joram_for_jonas_ra.rar archive file must provide the following
-information:
<jonas-config-property> - <jonas-config-property-name>HostName</jonas-config-property-name> - <jonas-config-property-value>hostA</jonas-config-property-value> -</jonas-config-property>- -
The other default settings do not need to be changed.
- -JOnAS B embedds JORAM server s1. The
-jonas-ra.xml descriptor packaged in the
-joram_for_jonas_ra.rar archive file must provide the following
-properties values:
<jonas-config-property> - <jonas-config-property-name>ServerId</jonas-config-property-name> - <jonas-config-property-value>1</jonas-config-property-value> -</jonas-config-property> -<jonas-config-property> - <jonas-config-property-name>ServerName</jonas-config-property-name> - <jonas-config-property-value>s1</jonas-config-property-value> -</jonas-config-property> -<jonas-config-property> - <jonas-config-property-name>HostName</jonas-config-property-name> - <jonas-config-property-value>hostB</jonas-config-property-value> -</jonas-config-property>- -
The other default settings do not need to be changed.
- -The shared queue will be hosted by JORAM server s1. It
-must then be declared in the JOnAS B's joramAdmin.xml file as
-follows:
- <Queue name="sharedQueue"> - <freeReader/> - <freeWriter/> - <jndi name="scn:comp/sharedQueue"/> - </Queue> -- -
The scn:comp/ prefix is a standard way to specify which JNDI
-provider should be used. In this case, the shared queue will be bound to
-JORAM's distributed JNDI server, and may be retrieved from both JOnAS A and
-JOnAS B. To provide this mechanism, both JOnAS servers must provide access to
-a standard jndi.properties file. For JOnAS A, the file looks as
-follows, and should be placed in its conf/ directory:
java.naming.factory.url.pkgs org.objectweb.jonas.naming:fr.dyade.aaa.jndi2 -scn.naming.factory.host hostA -scn.naming.factory.port 16400- -
For JOnAS B, the file looks as follows, and should be placed in the right
-conf/ directory:
java.naming.factory.url.pkgs org.objectweb.jonas.naming:fr.dyade.aaa.jndi2 -scn.naming.factory.host hostB -scn.naming.factory.port 16400- -
The simple bean on JOnAS A needs to connect to its local -JORAM server and access the remote queue. The following is an example of -consistent resource definitions in the deployment descriptors:
- -Standard deployment descriptor:
-<resource-ref> - <res-ref-name>jms/factory</res-ref-name> - <res-type>javax.jms.ConnectionFactory</res-type> - <res-auth>Container</res-auth> -</resource-ref> -<resource-env-ref> - <resource-env-ref-name>jms/sharedQueue</resource-env-ref-name> - <resource-env-ref-type>javax.jms.Queue</resource-env-ref-type> -</resource-env-ref>- -
Specific deployment descriptor:
-<jonas-resource> - <res-ref-name>jms/factory</res-ref-name> - <jndi-name>CF</jndi-name> -</jonas-resource> -<jonas-resource-env> - <resource-env-ref-name>jms/sharedQueue</resource-env-ref-name> - <jndi-name>scn:comp/sharedQueue</jndi-name> -</jonas-resource-env>- -
The ConnectionFactory is retrieved from the local JNDI registry of the -bean. However, the Queue is retrieved from the distributed JORAM JNDI server, -because its name starts with the scn:comp/ prefix. It is the same -queue to which the message-driven bean on JOnAS B listens. -For doing so, its activation properties should be set as follows:
-<activation-config> - <activation-config-property> - <activation-config-property-name>destination</activation-config-property-name> - <activation-config-property-value>scn:comp/sharedQueue</activation-config-property-value> - </activation-config-property> - <activation-config-property> - <activation-config-property-name>destinationType</activation-config-property-name> - <activation-config-property-value>javax.jms.Queue</activation-config-property-value> - </activation-config-property> -</activation-config>- - diff --git a/jonas_doc/olddoc/howto/JSR160_support.html b/jonas_doc/olddoc/howto/JSR160_support.html deleted file mode 100644 index d5616cd625c679913a63d51288e26cf03e742888..0000000000000000000000000000000000000000 --- a/jonas_doc/olddoc/howto/JSR160_support.html +++ /dev/null @@ -1,108 +0,0 @@ - - - - - -
The content of this document is the following:
- - -The target audience for this document is the management application - developer or the administrator, intending to use standard JMX RMI - connectors to access the MBean Server running in a JOnAS server. -
- --Currently, JSR 160 has defined a mandatory connector based on RMI (that -supports both RMI/JRMP and RMI/IIOP). -
-Support for JSR 160 connectors in JOnAS is based on the - MX4J JMX - implementation. -
- -RMIConnector_jonasServerName'. It can be accessed using any of
-the communication protocols support by JOnAS (RMI/JRMP, RMI/IIOP, JEREMIE -
-see Choosing the Protocol).
-
-JSR 160 support implies providing standard connector server objects. The JMX service
-creates at start-up one or several such objects, depending on the JOnAS configuration
-(in this case, depending on the content of carol.properties file).
-To create a client connector, the client side needs to know the URL of the connector
-server. Below we present the URLs that can be used by the clients depending on the
-protocol they choose.
Currently only 2 protocols can be used by JSR-160 connectors: -RMI/JRMP and RMI/IIOP. -
-jrmp protocol is set in the
- carol.protocols list.
-
-The client has to construct a JMXServiceURL using the following
-String, possibly modified according to the JOnAS-specific configuration:
-service:jmx:rmi:///jndi/rmi://host:port/jrmpconnector_jonasServerName
-where host is the host on which is running the JOnAS server to be managed.
-The port number is given in the carol.properties file.
Then, a JMXConnector has to be created and connected to the connector server
- using the JMX Remote API.
-
- Hashtable environment = null;
- JMXServiceURL address = new JMXServiceURL("service:jmx:rmi:///jndi/rmi://host:1099/jrmpconnector_jonas");
- JMXConnector connector = JMXConnectorFactory.newJMXConnector(address, environment);
- connector.connect(environment);
-
-
-iiop protocol is set in the
- carol.protocols list.
-
-The client code is similar to the JRMP case, but the String to be used to construct the JMXServiceURL
-must adhere to the following model:
-"service:jmx:iiop:///jndi/iiop://host:port/iiopconnector_jonasServerName"
- Hashtable environment = null;
- JMXServiceURL address = new JMXServiceURL("service:jmx:iiop:///jndi/iiop://host:2001/iiopconnector_jonas");
- JMXConnector connector = JMXConnectorFactory.newJMXConnector(address, environment);
- connector.connect(environment);
-
-
-
\ No newline at end of file
diff --git a/jonas_doc/olddoc/howto/JonasArchi.html b/jonas_doc/olddoc/howto/JonasArchi.html
deleted file mode 100644
index 8aab71f598bbcb18447a818aae1b72f983eb9168..0000000000000000000000000000000000000000
--- a/jonas_doc/olddoc/howto/JonasArchi.html
+++ /dev/null
@@ -1,1005 +0,0 @@
-
-
-
-
- Last modified at 2005-04-22, JOnAS 4.3
-
-
-
-
-
-This document provides an overview of the JOnAS platform architecture -design. The content of this document is the following:
-This document presents the internal architectural design of the JOnAS -application server. It contains many links toward the JOnAS documentation, -for detailed descriptions of some aspects.
- -JOnAS's service-based architecture provides for high modularity and -configurability of the server. It allows to apply a component-model approach -at the middleware level, and makes the integration of new modules easy (e.g. -for open source contributors). It also provides a way to start only the -services needed by a particular application, thus saving valuable system -resources. JOnAS services are manageable through JMX.
- -JOnAS is designed with services in mind. A service typically provides -system resources to containers. Most of the components of the JOnAS -application server are pre-defined JOnAS services. However, it is possible -and easy for an advanced JOnAS user to define a service and to integrate it -into JOnAS. Because J2EE applications do not necessarily need all services, -it is possible to define, at JOnAS server configuration time, the set of -services that are to be launched at server start.
- -The JOnAS architecture is illustrated in the following figure, showing WEB -and EJB containers relying on JOnAS services. Two thin clients are also shown -in this figure, one of which is the JOnAS administration console (called -JonasAdmin).
-
-
-All these services correspond to JOnAS components. The JOnAS Service -principle is described in detail within the JOnAS documentation, in the Creating -a New JOnAS Service section of the Advanced Topic chapter. Please read -this document to understand the JOnAS components wrapping within services. -Generally, a JOnAS service Serv1 implementation may be found -in the package org.objectweb.jonas.serv1, where an interface -of the service may be found, Serv1Service, with an -implementation, Serv1ServiceImpl, and an MBean for the -service management purpose (as described below in the JOnAS Management -Architecture section), Serv1ServiceImplMBean class.
- -An application server such as JOnAS must provide a complex class loading -scheme, which is described in the JOnAS -classloader hierarchy section of the J2EE Application Programmer's Guide -of the JOnAS documentation.
- -The following of this section describes the existing JOnAS services.
- -This service (also called "Registry") is used for launching the RMI -registry, the CosNaming and/or the CMI registry -depending on the JOnAS configuration (CAROL configuration, which specifies -which communication protocols are to be used). There are different registry -launching modes: in the same JVM or not, automatically if not already -running. CAROL enables multi-protocol runtime support and deployment, which -avoids having to redeploy components when changing the communication -protocol.
- -JOnAS may run several distributed processing environments, thanks to the -integration of the CAROL (Common -Architecture for RMI ObjectWeb Layer) ObjectWeb project, which allows -simultaneous support of several communication protocols:
-This service provides the JNDI API to application components and to other -services in order to bind and lookup remote objects (e.g. EJB Homes) and -resource references (JDBC DataSource, Mail and JMS connection factories, -etc.).
- - - -This service is in charge of loading the EJB components and their -containers. EJB containers consist of a set of Java classes that implement -the EJB specification and a set of interposition classes that interface the -EJB components with the services provided by the JOnAS application server. -The role of the interposed classes is to manage transactions, security, ... -Interposition classes are specific to each EJB component and are generated by -the deployment tool called GenIC. -This tool is developed using the Velocity template based generation tool.
- -For each EJB component XXX, GenIC generates the following classes:
-These files are generated with Velocity from templates located in org.objectweb.jonas_ejb.genic -(*.vm). Moreover, stubs and skeletons are generated, depending on the -specified protocol (jrmp/iiop), several protocols may be specified, -in this case several stubs/skeletons will be generated. CAROL is used to hide -the differencies between protocols.
- -For implementing Container-Managed Persistence of EJB 2.0 and EJB 2.1 -(CMP2), JOnAS relies on the ObjectWeb JORM (Java Object Repository Mapping) -and MEDOR (Middleware Enabling -Distributed Object Requests) frameworks. JORM supports complex mappings of -EJBs to database tables, as well as several types of persistency support -(relational databases, object databases, LDAP repositories, etc.). JORM is -responsible for bean persistence. MEDOR is used to evaluate ejb-ql -queries.
- -Generic objects used for entity beans are derived to be used by JORM:
-Typically, the PBinding uses the PAccessor to set and get field values in -the bean instance.
- -The lock policy is enforced in the JEntitySwitch class. Actually, this -class is specialized depending on the lock policy used:
-The detailed picture of the JOnAS CMP architecture is provided below:
-
-
-Each jar file is implemented in a separate Container. Each Container has a -swapper that is used to periodically write bean instances
- -on disk, and release memory instances from the cache when JOnAS needs more -memory.
- -For Message driven beans, the factory implements ServerSessionPool -interface. For each instance, an object (JMessageDrivenBean) is created : It -implements ServerSession, MessageListener, Runnable, and MessageDrivenContext -interfaces.
- -JOnAS configuration provides a means for specifying a set of ejb-jar files -to be loaded at server startup by the EJB container service. Ejb-jar files -can also be deployed at server runtime using the JOnAS administration -tools.
- -JOnAS also implements the Timer Service features as specified in EJB -2.1.
- -This service is in charge of running a Servlet/JSP Engine in the JVM of -the JOnAS server and of loading web applications ("war" files) within this -engine. Currently, this service can be configured to use Tomcat or Jetty. Servlet/JSP engines are -integrated within JOnAS as "web containers," i.e. such containers provide the -web components with access to the system resources (of the application -server) and to EJB components, in a J2EE-compliant way.
- -JOnAS configuration provides a means for specifying that this service be -launched during JOnAS initialization. Additionally, JOnAS configuration -provides a means for specifying a set of war files to be loaded at JOnAS -startup. War files may also be deployed at server runtime using the JOnAS -administration tools. User management for Tomcat/Jetty and JOnAS has been -unified. The class-loading delegation policy (priority to the Webapp -classloader or to the parent classloader) can be configured.
- -The
-web container service is implemented by using an abstract
-class (AbsJWebContainerServiceImpl) which needs to be extended to
-implement the specific Tomcat
-or Jetty
-part.
-The interface
-of this service defines common methods like starting, stopping the
-embedded server, or deploy/undeploy war files. Also, these public methods are
-available through an MBean.
-The class for Catalina 5.0 is named CatalinaJWebContainerServiceImpl
-and for Jetty 5.5 it is JettyJWebContainerServiceImpl.
-For Catalina 5.5, the name of the package is
-org.objectweb.jonas.web.catalina55 instead of
-org.objectweb.jonas.web.catalina50.
-To integrate a new web container, a new package
-org.objectweb.jonas.web.xxx should be added and the service
-class should extend AbsJWebContainerServiceImpl class.
For Tomcat, there are wrapper
-classes to use a specific
-classloader (Tomcat Classloader) instead of using the default classloader
-of all services running in JOnAS which is commons
-classloader.
-
Common tools to unpack wars, used by all implementations are in the -package org.objectweb.jonas.web.lib
- -There is another package for all the stuff concerning the parsing and the
-handling of web deployment descriptors. This is the package org.objectweb.jonas_web.deployment
-which is composed of api package (used by web container service) and the
-other subpackages are only used internally for parsing and managing the XML
-files.
-The only import which should occur within a web container service
-implementation should be the api package and not the other subpackages. This
-allows to change the implementation of parsing/analyzing XML files without
-changing the services code.
This service is used for deploying complete J2EE applications, i.e. -applications packaged in EAR files, which themselves contain ejb-jar files -and/or war files. This service handles the EAR files and delegates the -deployment of the war files to the WEB Container service and the ejb-jar -files to the EJB Container service. It handles creating the appropriate class -loaders, in order for the J2EE application to execute properly.
- -For deploying J2EE applications, JOnAS must be configured to launch the -EAR service and to specify the set of EAR files to be loaded. EAR files can -also be deployed at server runtime using the JOnAS administration tools.
- -This service is implemented by the EarServiceImpl
-class. This class is linked to other services which should be started. The
-ear service needs an EJB service and a WebContainer service to allow to send
-EJBs of an EAR to the EJB service and to send web components to the web
-container service.
-This service is pretty simple, it unpacks EAR, resolves "Class-Path:" entries
-of MANIFEST files and ejb-link elements, and set up JACC security. Once
-everything is correctly setup, it send components to each service (ejb or
-web) which will deploy them by using information provided by the Ear
-service.
As explained in web container service, all the parsing/handling of XML -deployment descriptors is done in another package which is for Ear service -the org.objectweb.jonas_ear.deployment -package.
- -This service encapsulate a Java Transaction Monitor called JOTM (a project from ObjectWeb). It is a -mandatory service which handles distributed transactions. It provides -transaction management for EJB components as defined in their deployment -descriptors. It handles two-phase commit protocol against any number of -Resource Managers (XA Resources). For J2EE, a transactional resource may be a -JDBC connection, a JMS session, or a J2EE CA Resource Adapter connection. The -transactional context is implicitly propagated with the distributed requests. -The Transaction Monitor can be distributed across one or more JOnAS servers; -thus a transaction may involve several components located on different JOnAS -servers. This service implements the JTA 1.0.1 specification, thus allowing -transactions from application components or from application clients to be -explicitly started and terminated. Starting transactions from application -components is only allowed from Web components, session beans, or -message-driven beans (only these two types of beans, which is called -"Bean-managed transaction demarcation").
- -The Transaction service may be found in the org.objectweb.jonas.jtm -package.
- -This service is responsible for handling Datasource objects. A Datasource -is a standard JDBC administrative object for handling connections to a -database. The Database service creates and loads such datasources on the -JOnAS server. Datasources to be created and deployed can be specified at -JOnAS configuration time, or they can be created and deployed at server -runtime using the JOnAS administration tools. The Database service is also -responsible for connection pooling; it manages a pool of database connections -to be used by the application components, thus avoiding many physical -connection creations, which are time-consuming operations.
-The database service should now be replaced by the JDBC Resource Adapter, to be deployed -by the J2EE CA Resource Service (see below), which additionally provides JDBC -PreparedStatement pooling. - -The Database Service is implemented in the org.objectweb.jonas.dbm -package.
- -For supporting Message-driven Beans and JMS operations coded within -application components, the JOnAS application server relies on a JMS -implementation. JOnAS makes use of a third-party JMS implementation; -currently the JORAM open source -software is integrated and delivered with JOnAS, the SwiftMQ product has also been used in -previous versions of JOnAS, and other JMS provider implementations can easily -be integrated. JORAM provides several noteworthy features: in particular, -reliability (with a persistent mode), distribution (transparently to the JMS -client, it can run as several servers, thus allowing load balancing), and the -choice of TCP or SOAP as communication protocol for transmitting messages.
- -The JMS service is in charge of launching (or establishing connection to) -the integrated JMS server, which may or may not run in the same JVM as JOnAS. -It also provides connection pooling and thread pooling (for Message-driven -Beans). Through this service, JOnAS provides facilities to create -JMS-administered objects such as the connection factories and the -destinations, either at server launching time or at runtime using the JOnAS -administration tools.
- -This service is implemented in the org.objectweb.jonas.jms -package.
- -Note that the same function of JMS implementation integration should now -be achieved through a Resource Adapter, to be deployed by the J2EE CA -Resource Service (see below). Such a Resource Adapter (J2EE CA 1.5) is provided for -JORAM. The Messaging service will become deprecated.
- -The J2EE Connector Architecture (J2EE CA) allows the connection of -different Enterprise Information Systems (EIS) to a J2EE application server. -It is based on the Resource Adapter (RA), an architecture component -comparable to a software driver, which connects the EIS, the application -server, and the enterprise application (J2EE components). The RA is generally -provided by an EIS vendor and provides a Java interface (the Common Client -Interface or CCI) to the J2EE components for accessing the EIS (this can also -be a specific Java interface). The RA also provides standard interfaces for -plugging into the application server, allowing them to collaborate to keep -all system-level mechanisms (transactions, security, and connection -management) transparent from the application components.
-The application performs "business logic" operations on the EIS data using -the RA client API (CCI), while transactions, connections (including pooling), -and security on the EIS are managed by the application server through the RA -(system contract). - -The JOnAS Resource service is in charge of deploying J2EE CA-compliant -Resource Adapters (connectors), packaged as RAR files, on the JOnAS server -(such connectors will be loaded in the Application classloader). RAR files -can also be included in EAR files, in which case the connector will be loaded -by classloader of the EAR. Once Resource Adapters are deployed, a connection -factory instance is available in the JNDI namespace to be looked up by -application components.
- -The Resource Service is implemented in the org.objectweb.jonas.resource -package.
- -A J2EE CA 1.5 Resource Adapter for JDBC is available with JOnAS. It can -replace the current JOnAS database service for plugging JDBC drivers and -managing connection pools. It also provides JDBC PreparedStatement -pooling.
- -A J2EE CA 1.5 Resource Adapter for JMS is available with JOnAS. It can -replace the current JOnAS Messaging service for plugging JORAM.
- - -This service implements the authorization mechanisms for accessing J2EE -components, as specified in the J2EE specification.
- -In JOnAS, the mapping between roles and user identification is done in the -user identification repository. This user identification repository can be -stored either in files, in a JNDI repository (such as LDAP), or in a -relational database. This is achieved through a JOnAS implementation of the -Realm for each Web container and through the JAAS login modules for Java -clients. These Realms use authentication resources provided by JOnAS, which -rely either on files, LDAP or JDBC. These realms are in charge of propagating -the security context to the EJB container during EJB calls. JAAS login -modules are provided for user authentication of Web Container and Java -clients. Certificate-based authentication is also available, with -CRLLoginModule login module for certificate revocation.
- -JOnAS also implements the Java Authorization Contract for Containers (JACC -1.0) specification, allowing authorizations to be managed as java security -permissions, and providing the ability to plug any security policy -provider.
- -More details about security handling within JOnAS is provided within the -Configuring -Security section of the JOnAS Configuration Guide.
- -There are 3 major packages for implementing the security in JOnAS.
-org.objectweb.jonas.security.realm.web.xxx where xxx is
- catalina50, catalina55, jetty50, etc.The Management service is needed to administrate a JOnAS server from the -JOnAS administration console. Each server running this service is visible -from the administration console. This service is based on JMX. Standard -MBeans are defined within the JOnAS application server; they expose the -management methods of the instrumented JOnAS server objects such as services, -containers, the server itself. These MBeans implements the management model -as specified in the J2EE Management Specification. The Management service -runs a JMX server - , and is implemented in the org.objectweb.jonas.jmx -package. The MBeans of the JOnAS server are registered within this JMX -server. The JOnAS administration console is a Struts-based Web application -(servlet/JSP) that accesses the JMX server to present the managed features -within the administration console. Thus, through a simple Web browser, it is -possible to manage one or several JOnAS application servers. The -administration console provides a means for configuring all JOnAS services -(and making the configuration persistent), for deploying any type of -application (EJB-JAR, WAR, EAR) and any type of resource (DataSources, JMS -and Mail connection factories, J2EE CA connectors), all without the need to -stop or restart the server. The administration console displays information -for monitoring the servers and applications, such as used memory, used -threads, number of EJB instances, which component currently uses which -resources, etc.. When Tomcat is used as Web Container, the Tomcat Management -is integrated within the JOnAS console. A Management EJB (MEJB) is also -delivered, providing access to the management features, as specified in the -J2EE Management Specification.
- -The discovery service is used to support domain management. A JOnAS -management domain is composed of a set of JOnAS servers that are running -under the same management authority and are identified by a domain name. The -servers in a domain may be administred by a management application running on -one server in the domain; this is the master server. The managed servers are -slaves. The discovery service is based on a mutlicast communication -infrastructure allowing message broadcasting in order to publish the -connector-server addresses and state changes of the servers in the domain. -The master servers listen to these discovery messages. Moreover, they are -able to broadcast messages asking the servers in the domain to identify -themselves
- -A J2EE application component can send e-mail messages using JavaMailTM. The -Mail service of the JOnAS application server provides the necessary resources -to such application components. The Mail service creates mail factories and -registers these resources in the JNDI namespace in the same way that the -database service or the JMS service creates Datasources or -ConnectionFactories and registers these objects in the JNDI namespace. There -are two types of mail factories: javax.mail.Session and -javax.mail.internet.MimePartDataSource.
- -The Mail service is implemented in the org.objectweb.jonas.mail -package.
- -This service is implemented on top of AXIS and is used for the deployment of
-Web Services. Only a very small part of the deployment work is done during
-the installation time: most of the work is done offline with a tool like
-GenIC, WsGen.
-
-
WsGen will build server side artifacts if a webservices.xml descriptor is
-found in the archive (can be an EjbJar or a WebApp):
-
Client side artifacts are generated only if WsGen find some service-ref
-elements in web.xml, ejb-jar.xml or application-client.xml:
-
2 main packages:
-
Webservices related documentation :
-
As previously explained, JOnAS Management is based on JMX. Standard MBeans -are defined within the JOnAS application server; they expose the management -methods of the instrumented JOnAS server objects such as services, -containers, the server itself. They are registered within the JMX server -embedded within the JOnAS Management Service, and may then be accessed by any -JMX client.
- - - -
Related documentation:
- -Domain -Management in JOnAS (explain the domain management feature of JOnAS, -available from JOnAS 4.4 only)
- -Discovery -Service Configuration (description of the discovery service, used for -domain support, available from JOnAS 4.4 only)
- -JSR160 -Support in JOnAS (explain the principles to remotely access to the JOnAS -MBeans server, e.g. for remote management, used by the domain management -features)
- -Administration -Guide (JonasAdmin console principles, MEJB description)
- -Working with -Management Beans (key and short document to understand JOnAS management -principles)
- -JOnAS -and JMX, registering and manipulating MBeans (contributed document -explaining how to register applicative MBeans within the JOnAS JMX server)
- - - -Clustering for an application server generally makes use of three -features: Load Balancing (LB), High Availability (HA) and Failover. Such -mechanisms can be provided at the Web container level by dispatching requests -to several Servlet/JSP engine instances, at the EJB container level by -dispatching EJB requests to several EJB container instances, and at the -database level by using several databases. A replicated JNDI naming is also -necessary.
- -JOnAS provides Load Balancing, HA, and Failover at the WEB container level -using the Apache Tomcat mod_jk plugin and an HTTP in memory -session-replication mechanism provided with Tomcat. The plugin dispatches -HTTP requests from the Apache web server to Tomcat instances running as JOnAS -web containers. Server fluctuations are automatically taken into account. -This plugin supports round-robin and weighted round-robin load-balancing -algorithms, with a sticky session option.
- -Load balancing and HA are provided at the EJB container level in JOnAS. -Operations invoked on EJB Home interfaces (EJB creation and retrieval) are -dispatched on the nodes of the cluster. The mechanism is based on a -"clustered-aware" replicated JNDI registry using a Clustered remote Method -Invocation protocol (CMI). The stubs contain the knowledge of the cluster and -implement the load-balancing policy, which may be random, round-robin and -weighted round-robin. Failover at the EJB level will be provided by -implementing a stateful session bean state replication mechanism.
- -The JOnAS clustering architecture is illustrated in the following -figure.
-
-
-JOnAS provides documentation for configuring such an architecture, the JOnAS -Clustering Document.
- -The use of the C-JDBC ObjectWeb -project offers load balancing and high availability at the database level. -The use of C-JDBC is transparent to the application (in our case to JOnAS), -since it is viewed as a standard JDBC driver. However, this "driver" -implements the cluster mechanisms (reads are load-balanced and writes are -broadcasted). The database is distributed and replicated among several nodes, -and C-JDBC load balances the queries between these nodes. An evaluation of -C-JDBC using the TPC-W benchmark on a 6-node cluster has shown performance -scaling linearly up to six nodes.
- -In addition to clustering solutions, JOnAS provides many mechanisms, -intrinsic to the JOnAS server, for being highly scalable and efficient. This -includes the following:
-Optimizations related to entity beans are described in the Tuning -Container for Entity Bean Optimizations section of the JOnAS -documentation. More details about available CMP tuning features are provided -below.
- -JOnAS provides many CMP tuning features, which may be specified through -server specific deployment elements, at the entity bean level (so that one -policy per component may be defined).
- - - -1) Lock Policy (Concurrent Access)
- -The <lock-policy> elements may have the following value:
-Note: If you deploy CMP1 beans, you should use the default policy only -(container-serialized), unless your beans are "read-only". In this latter -case, you can use container-read-uncommitted.
- -2) Database dedicated access
- -JOnAS can do some data access optimization if the persistent state of an -entity bean is accessed only by the JOnAS server. The optimization consists -in not re-reading the bean state before starting a new transaction if the -bean is already in memory. Indeed, as nobody else can modify the state of the -bean on the persistent support, it is not necessary to re-read it. This may -be specified to JOnAS by using the <shared> element -and setting it to false. If the <shared> element is set to true, it -means that the bean persistent state can be accessed outside the JOnAS -Server, and then the optimization cannot be done. The default value is false -if lock-policy is container-serialized, and true in the other cases.
- -3) Data pre-fetching
- -The <prefetch> element is a CMP2-specific option. -The default is false. This can be set to true if it is desirable to have a -cache managed after finder methods execution, in order to optimize further -accesses, inside the same transaction.
- -Important notes:
-4) Instances pooling / caching
- -Four elements allow specifying entity beans instances management.
- -- The first one, <max-cache-size>, is an integer -value that represents the maximum number of instances in memory. The purpose -of this value is to keep JOnAS scalable. The default value is "no limit". To -save memory, this value should be set very low if you know that instances -will not be reused.
- -- The second one, <min-pool-size>, is an integer -value representing the number of instances that will be created in the pool -when the bean is loaded. This will improve bean instance creation time, at -least for the first instances. The default value is 0.
- -- The third one, <passivation-timeout>, allows -tuning the entity bean instances passivation activity (saving memory by -sending instances on the persistent support), in accordance with the previous -persistence tuning elements. Entity bean instances are passivated at the end -of each transaction and reactivated at the beginning of the next transaction, -when the shared flag has been set to true. In case shared has been set to -false, a passivation will occur only if max-cache-size has been reached. In -the event that these instances are accessed outside a transaction, their -state is kept in memory to improve performance. However, a passivation will -occur in three situations:
-- The fourth one is <inactivity-timeout>: Bean -passivation sends to persistent storage the state of the bean and removes -from memory only the bean instance objects holding this state. All container -objects handling bean access (remote object, interceptors ...) are kept in -memory so that future access will work, only requiring a reload operation -(getting the state). You may want to save more memory and completely remove -the bean instance from memory, this may be achieved through the -<inactivity-timeout> element. This element is used to save memory when -a bean has not been used for a long time. After the time specified, in -seconds, and if the bean has not been used meanwhile, all its container -objects are removed from the server. If a client has kept a reference on a -remote object, it will get an exception if it tries to use it.
- -5) Db Connections pooling
- -For database access, JOnAS provides a sophisticated connection pools -management. See the Configuring -JDBC Datasource section of the JOnAS Configuration Guide (available soon -for the JDBC connector). Connection pooling saves the high cost of physical -connection creation by maintaining a pool of such connections. Connection -pools may be tuned using the following properties:
-6) PreparedStatement pooling
- -The JOnAS JDBC connector manages pools of JDBC PreparedStatements.
- -Sun, Java, and all -Java-based trademarks are trademarks or registered trademarks of Sun -Microsystems, Inc. in the U.S. and other countries.
- - diff --git a/jonas_doc/olddoc/howto/JonasMBeansHowTo.html b/jonas_doc/olddoc/howto/JonasMBeansHowTo.html deleted file mode 100644 index b2e3f43e5a5d4b004e1ea61573d70548955a369b..0000000000000000000000000000000000000000 --- a/jonas_doc/olddoc/howto/JonasMBeansHowTo.html +++ /dev/null @@ -1,419 +0,0 @@ - - - - - -By Jonny Way.
-JMX (Java Management eXtensions) is an API for managing, among other -things, J2EE applications. JOnAS (version 4 and above) integrates the MX4J -open-source JMX server and registers a number of MBeans. The web-based -JonasAdmin application acts as a JMX client, enabling viewing and -manipulation of these MBeans.
- -It maybe desirable for an application to expose its own MBeans via the JMX -server to allow application management (using, for example, MC4J). JOnAS -currently does not provide a prebuilt method for registering MBeans with its -JMX server. The intent of this document is to illustrate one method of registering -application-specific MBeans with the JOnAS JMX server based on the m-let -service.
- -The basic task of registering an MBean with the JOnAS JMX server is -accomplished by the following implementation of the ServletContextListener -interface. This implementation reads a number of MLet files, which specify the -MBeans to be registered, and attempts to register those beans during the web -application context initialization.
-
-import java.net.MalformedURLException;
-import java.net.URL;
-import java.util.Iterator;
-import java.util.ArrayList;
-import java.util.List;
-import java.util.Set;
-import java.util.StringTokenizer;
-
-import javax.management.InstanceAlreadyExistsException;
-import javax.management.InstanceNotFoundException;
-import javax.management.ReflectionException;
-import javax.management.MBeanServer;
-import javax.management.MBeanException;
-import javax.management.MBeanRegistrationException;
-import javax.management.MBeanServerFactory;
-import javax.management.MalformedObjectNameException;
-import javax.management.NotCompliantMBeanException;
-import javax.management.ObjectInstance;
-import javax.management.ObjectName;
-import javax.management.loading.MLet;
-import javax.management.loading.MLetMBean;
-import javax.servlet.ServletContextEvent;
-import javax.servlet.ServletContext;
-import javax.servlet.ServletContextListener;
-
-import org.apache.log4j.Logger;
-
-/**
- * ServletContextListener designed to register JMX MBeans into
- * an existing JMX server when the application starts up. The
- * MBeans to be loaded are specified in the MLet files whose
- * names are given in the servlet context parameter with the name mletFiles,
- * in a semi-colon delminated list (although this is not really
- * needed as multiple mlets can be specifyed in one file, it might
- * be useful). Note that the filename are relative to the WEB-INF
- * directory of the servlet context being listened to.
- *
- * Note, that this listener should precede (in web.xml) any other that depend
- * on the MBeans being registered.
- *
- * Note that the MBean registration is sensitive to classloader issues. For
- * example, when registering the MBeans in the JMX server provided by
- * the Jonas application server any libraries required by the MBeans need
- * to be in the central lib directory (lib/ext).
- *
- *
- * @author Jonny Wray
- *
- */
-public class MBeanRegistrationListener implements ServletContextListener {
-
- private static final String MLET_DOMAIN = "MBeanRegistrationListener";
- private static final String MLET_BEAN_NAME = MLET_DOMAIN+":Name=MLet";
- private static final String MLETFILE_INITPARAM_NAME = "mletFiles";
- private static final Logger log = Logger.getLogger(MBeanRegistrationListener.class);
-
-
- private MBeanServer lookForExistingServer(){
- List mbeanServers = MBeanServerFactory.findMBeanServer(null);
- if(mbeanServers != null && mbeanServers.size() > 0){
- return (MBeanServer)mbeanServers.get(0);
- }
- return null;
- }
-
- private MBeanServer getMBeanServer(){
- MBeanServer server = lookForExistingServer();
- if(server == null){
- server = MBeanServerFactory.createMBeanServer(MLET_DOMAIN);
- }
- return server;
- }
-
-
- public void contextDestroyed(ServletContextEvent arg0) {
- log.info("Destroy event");
- // Anything that needs to be done here on deregistering of the
- // web application?
- }
-
-
- private List getMLetURLs(String filenames){
- List urls = new ArrayList();
- StringTokenizer tok =
- new StringTokenizer(filenames, ";");
- while(tok.hasMoreTokens()){
- String filename = tok.nextToken();
- URL configURL = Thread.currentThread().getContextClassLoader().getResource(filename);
- if(configURL == null){
- log.error("Cound not load MLet file resource from "+filename+" using current thread context classloader");
- }
- else{
- urls.add(configURL);
- }
- }
- return urls;
- }
-
- private List getMLetURLs(ServletContext context, String filenames){
- List urls = new ArrayList();
- StringTokenizer tok =
- new StringTokenizer(filenames, ";");
- while(tok.hasMoreTokens()){
- String filename = "/WEB-INF/"+tok.nextToken();
- URL configURL = null;
- try {
- configURL = context.getResource(filename);
- }
- catch (MalformedURLException e) {
- log.error("URL for "+filename+" is malformed", e);
- }
- if(configURL == null){
- log.error("Cound not find MLet file resource from "+filename+" in servlet context");
- }
- else{
- urls.add(configURL);
- }
- }
- return urls;
- }
-
- /**
- * Dynamically register the MBeans specified in the list
- * of MLet files (relative to /WEB-INF/) specified in servlet context parameter
- * mletFiles as a semi-colon deliminated list of file names.
- *
- * The algorithm looks for already running JMX servers and uses
- * the first it comes across. If no servers are running, then
- * it creates one.
- *
- * Note, the interface does not define any exceptions to be
- * thrown. Currently, any exceptions thrown during registration
- * are logged at error level and then ignored. This seems
- * reasonable, as these may or may not be a fatal event. In
- * this way the registration process reports its failure and
- * the application context initialization continues.
- */
- public void contextInitialized(ServletContextEvent arg0) {
- log.info("Initializing event");
- String filenames = arg0.getServletContext().getInitParameter(MLETFILE_INITPARAM_NAME);
- if(filenames != null && filenames.length() > 0){
- MBeanServer server = getMBeanServer();
- if(server != null){
- try{
- ObjectName name = new ObjectName(MLET_BEAN_NAME);
- if(!server.isRegistered(name)){
- log.info("Creating new MLetMBean for dynamic registration");
- MLetMBean mletService = new MLet();
- server.registerMBean(mletService, name);
- }
- List urls = getMLetURLs(arg0.getServletContext(), filenames);
- for(int i=0;i < urls.size();i++){
- URL url = (URL)urls.get(i);
- try {
- log.info("Registering MBeans from MLet file "+url);
- Set loadedMBeans = (Set)server.invoke(name, "getMBeansFromURL",
- new Object[]{url}, new String[]{URL.class.getName()});
-
- processRegisteredMBeans(loadedMBeans);
- }
- catch (InstanceNotFoundException e) {
- log.error("Unable to register MBeans from MLet file "+url, e);
- }
- catch (MBeanException e) {
- log.error("Unable to register MBeans from MLet file "+url, e);
- }
- catch (ReflectionException e) {
- log.error("Unable to register MBeans from MLet file "+url, e);
- }
- }
- }
- catch(MalformedObjectNameException e){
- log.error("Unable to register the MLetMBean", e);
- }
- catch(NotCompliantMBeanException e){
- log.error("Unable to register the MLetMBean", e);
- }
- catch(MBeanRegistrationException e){
- log.error("Unable to register the MLetMBean", e);
- }
- catch(InstanceAlreadyExistsException e){
- log.error("Unable to register the MLetMBean", e);
- }
- }
- else{
- log.error("MBeanServer not found and could not be created. Not registering MBeans.");
- }
- }
- else{
- log.error("No mletFiles servlet context parameter found.");
- }
- }
-
- private void processRegisteredMBeans(Set loadedMBeans) {
- log.debug("Loaded beans: "+loadedMBeans.size());
- Iterator it = loadedMBeans.iterator();
- while(it.hasNext()){
- Object o = it.next();
- if(o instanceof ObjectInstance){
- ObjectInstance inst = (ObjectInstance)o;
- log.info("Registered: "+inst.getObjectName());
- }
- else if(o instanceof Throwable){
- Throwable err = (Throwable)o;
- log.error("Error registering MBeans", err);
- }
- }
- }
-
-}
- In order to use the above ServletContextListener, it must be configured -in the web.xml of the web application that wants to register the MBeans. For -example, the following lines added to the web.xml will result in the -registeration of the MBeans specified in the application.mlet file under the -WEB-INF directory. Multiple MLet files can be specified in a comma-separated -list.
-
- <context-param>
- <param-name>mletFiles</param-name>
- <param-value>application.mlet</param-value>
- </context-param>
-
- <listener>
- <listener-class>net.fiveprime.jmx.MBeanRegistrationListener</listener-class>
- </listener>
- An example MLet file to load an extension (detailed below) of the
-HibernateService MBean is:
<mlet code="ConfigurableHibernateService" - name="HibernateService:Name=HibernateService" - archive="mbeans.jar"> - <arg type="java.lang.String" value="hibernate.cfg.xml"> - <arg type="java.lang.String" value="hibernate/HibernateSessionFactory"> - <arg type="java.lang.String" value="DefaultDS"> -</mlet> -- -
Registration of MBeans results in their construction by the JMX server. As -such, any classes the MBean is dependent on must be available to the JMX -server, in lib/ext.
- -The Hibernate distribution provides an implementation of -HibernateServiceMBean in the class HibernateService. In the MLet file above, -an extension of this class is specified that allows the HibernateService to be -configured from an external file, such as the standard hibernate.cfg.xml -file. There are a number of situations where it is desirable to use the Hibernate mapped -classes outside of Jonas running a JMX server. This allows the -Hibernate mapping files and properties to be specified in one place and used in multiple -situations. If this is not needed, then the HibernateService class can be -used directly.
-
-import java.io.IOException;
-import java.net.URL;
-import java.util.ArrayList;
-import java.util.HashMap;
-import java.util.Iterator;
-import java.util.List;
-import java.util.Map;
-
-import net.sf.hibernate.HibernateException;
-import net.sf.hibernate.jmx.HibernateService;
-
-import org.apache.commons.digester.Digester;
-import org.apache.commons.logging.Log;
-import org.apache.commons.logging.LogFactory;
-import org.xml.sax.SAXException;
-/**
- * Extension of the HibernateService class to add configuration
- * ability from a Hibernate XML configuration file.
- *
- * @author Jonny Wray
- *
- */
-public class ConfigurableHibernateService extends HibernateService {
-
- private static Log log = LogFactory.getLog(ConfigurableHibernateService.class);
-
- /**
- * Configure this HibernateService from an XML file
- *
- * @param filename The Hibernate XML configuration file, for example hibernate.cfg.xml
- * @param jndiName The JNDI name that the session factory will be registered under
- * @param datasourceName The name of the datasource used by the session factory
- * @throws HibernateException If there's a problem reading the configuration file
- */
- public ConfigurableHibernateService(String filename, String jndiName, String datasourceName)
- throws HibernateException{
-
- init(filename, jndiName, datasourceName);
- start();
- }
-
- private void init(String filename, String jndiName, String datasourceName) throws HibernateException {
- if(log.isDebugEnabled()){
- log.debug("Configuring Hibernate JMX MBean with filename "+filename+
- ", JNDI name "+jndiName+" and datasource "+datasourceName);
- }
- try{
- URL url = this.getClass().getClassLoader().getResource(filename);
- Digester mappingDigester = configureMappingDigester();
- List results = (List)mappingDigester.parse(url.openStream());
- Iterator it = results.iterator();
- while(it.hasNext()){
- StringBuffer buffer = (StringBuffer)it.next();
- addMapResource(buffer.toString());
- log.debug("Adding mapping resource "+buffer.toString());
- }
-
- Digester propertyDigester = configurePropertyDigester();
- Map resultMap = (Map)propertyDigester.parse(url.openStream());
- it = resultMap.keySet().iterator();
- while(it.hasNext()){
- String key = (String)it.next();
- String value = (String)resultMap.get(key);
- setProperty("hibernate."+key, value);
- log.debug("Adding property ("+key+","+value+")");
- }
- setJndiName(jndiName);
- setDatasource(datasourceName);
- }
- catch(IOException e){
- throw new HibernateException(e);
- }
- catch(SAXException e){
- throw new HibernateException(e);
- }
- }
-
- private Digester configureMappingDigester(){
- Digester digester = new Digester();
- digester.setClassLoader(this.getClass().getClassLoader());
- digester.setValidating(false);
- digester.addObjectCreate("hibernate-configuration/session-factory", ArrayList.class);
-
- digester.addObjectCreate("hibernate-configuration/session-factory/mapping", StringBuffer.class);
- digester.addCallMethod("hibernate-configuration/session-factory/mapping", "append", 1);
- digester.addCallParam("hibernate-configuration/session-factory/mapping", 0, "resource");
- digester.addSetNext("hibernate-configuration/session-factory/mapping", "add");
-
- return digester;
- }
-
- private Digester configurePropertyDigester(){
- Digester digester = new Digester();
- digester.setClassLoader(this.getClass().getClassLoader());
- digester.setValidating(false);
- digester.addObjectCreate("hibernate-configuration/session-factory", HashMap.class);
-
- digester.addCallMethod("hibernate-configuration/session-factory/property", "put", 2);
- digester.addCallParam("hibernate-configuration/session-factory/property", 0, "name");
- digester.addCallParam("hibernate-configuration/session-factory/property", 1);
-
- return digester;
- }
-}
-
- This document explains how WebSphere MQ (formerly MQSeries) can be used as -JMS provider within a JOnAS application server.
- -WebSphere MQ is the messaging platform developed by IBM. It provides Java -and JMS interfaces. Documentation is located at -http://www-3.ibm.com/software/integration/mqfamily/library/manualsa/.
- -This document was written after integration work done with JOnAS 3.3 and -3.3.1 and WebSphere MQ 5.3.
-This document may be used only when working with JOnAS 3.3
-Since JOnAS 4.8 a specific resource adaptor JCA JOnAS-MQ is available for accessing to WebSphere MQ. -The corresponding documentation is currently being written and will be available soon.
- -The content of this guide is the following:
-WebSphere MQ, contrary to JORAM or SwiftMQ, cannot run collocated with -JOnAS. WebSphere MQ is an external software which must be independently -administered and configured.
- -Administering WebSphere MQ consists of the following:
-The link between JOnAS and WebSphere MQ is established via the registry. -WebSphere MQ JMS objects are bound to the JOnAS registry. JMS lookups will -then return the WebSphere MQ JMS objects, and messaging will take place -through these objects.
- -Given the complex configuration of WebSphere MQ JMS objects, it is not -possible to create these objects from JOnAS. Therefore, during the starting -phase, a JOnAS server expects that WebSphere MQ JMS objects have already been -bound to the registry. Thus it is necessary to start an independent registry -to which WebSphere MQ can bind its JMS objects, and which can also be used by -the starting JOnAS server. The start-up sequence looks like the following:
-The following architecture is proposed:
-The proposed architecture requires running two JOnAS server instances. For -this, the following steps are proposed:
-The JOnAS servers can now be configured independently.
- -The "Registry" server is the JOnAS server that will host the registry -service. Its configuration files are in JONAS_REGISTRY/conf.
- -In the jonas.properties files, declare only the registry and jmx -services:
- -jonas.services registry,jmx
- -In the carol.properties file, declare the jeremie protocol:
- -carol.protocols=jeremie
- -Its port can also be configured:
- -carol.jeremie.url=jrmi://localhost:2000
- -The "EJB" server is the JOnAS server that will be used as the application -server. Its configuration files are in JONAS_EJB/conf. Libraries -must be added in JONAS_EJB/lib/ext.
- -In the jonas.properties files, set the registry service as remote:
- -jonas.service.registry.mode remote
- -... and the JMS service as WebSphere MQ:
- -jonas.service.jms.mom org.objectweb.jonas_jms.JmsAdminForWSMQ
- -In the carol.properties file, declare the jeremie protocol and set the -correct port:
- -carol.protocols=jeremie
-carol.jeremie.url=jrmi://localhost:2000
In lib/ext, the following libraries must be added:
-WebSphere MQ JMS administration is documented in chapter 5 of the -"WebSphere MQ Using Java" document.
- -The configuration file of the JMS administration tool must be edited so -that the JOnAS registry is used for binding the JMS objects. This file is the -JMSAdmin.config file located in WebSphereMQ's Java/bin -directory. Set the factory and provider URL as follows:
- -INITIAL_CONTEXT_FACTORY=org.objectweb.jeremie.libs.services.registry.
-
- jndi.JRMIInitialContextFactory
-PROVIDER_URL=jrmi://localhost:2000
The JOnAS's client.jar library must also be added to the -classpath for WebSphere MQ.
- -When starting, JOnAS expects JMS objects to have been created and bound to -the registry. Those objects are connection factories, needed for connecting -to WebSphere MQ destinations, and destinations.
- -JOnAS automatically tries to access the following factories:
-If one of these objects cannot be found, JOnAS will print a message that -looks like the following:
- -JmsAdminForWSMQ.start : WebSphere MQ -XAConnectionFactory could not be retrieved from JNDI
- -This does not prevent JOnAS from working. However, if there is no -connection factory available, no JMS operations will be possible from -JOnAS.
- -If destinations have been declared in the jonas.properties file, -JOnAS will also expect to find them. For example, if the following -destinations are declared:
- -jonas.service.jms.topics sampleTopic
-jonas.service.jms.queues sampleQueue
The server expects to find the following JMS objects in the registry:
-If one of the declared destination cannot be retrieved, the following -message appears and the server stops:
- -JOnAS error: -org.objectweb.jonas.service.ServiceException : Cannot init/start service -jms': org.objectweb.jonas.service.ServiceException : JMS Service Cannot -create administered object: java.lang.Exception: WebSphere MQ Queue creation -impossible from JOnAS
- -Contrary to connection factories, the JOnAS administration tool allows -destinations to be created. Since it is not possible to create WebSphere MQ -JMS objects from JOnAS, this will work only if the destinations are -previously created and bound to the registry.
- -For example, if you want to create a queue named "myQueue" through the -JonasAdmin tool, this will only work if:
-To launch WebSphere MQ administration tool, type: JMSAdmin
- -The following prompt appears: InitCtx>
- -To create a QueueConnectionFactory and binding it with name -"JQCF", type:
- -InitCtx> DEF QCF(JQCF)
- -More parameters can be entered (for example for specifying the queue -manager).
- -To create a Queue that represents a WebSphere MQ queue named -"myWSMQqueue", and to bind it with name "sampleQueue", type:
- -InitCtx> DEF Q(sampleQueue) -QUEUE(myWSMQqueue)
- -Objects bound in the registry can be viewed by typing:
- -InitCtx> DIS CTX
- -To start the registry server:
-To administer WebSphere MQ:
-To start the EJB server:
-To start an EJB client:
-Using WebSphere MQ as JMS transport within JOnAS has some limitations, as -compared with using JORAM or SwiftMQ.
- -First of all, WebSphere MQ is compliant with the old 1.0.2b JMS -specifications. Code that is written following the JMS 1.1 latest spec (such -as the jms samples provided with JOnAS) will not work with WebSphere MQ.
- -Depending on the WebSphere MQ distribution, JMS Publish/Subscribe may not -be available. In this case, the message-driven bean samples provided with -JOnAS will not work. For this reason, a specific sample is provided.
- -Finally, for an unknown reason, asynchronous consumption of messages -(through message-driven beans) does not work in transactional mode. Further -inquiry is needed to resolve this issue.
- - diff --git a/jonas_doc/olddoc/howto/Win32Service.html b/jonas_doc/olddoc/howto/Win32Service.html deleted file mode 100644 index 8e846bdcbe4a036374a7190b9eb3cf7ac642a54d..0000000000000000000000000000000000000000 --- a/jonas_doc/olddoc/howto/Win32Service.html +++ /dev/null @@ -1,261 +0,0 @@ - - - - -This document describes the procedures necessary to run JOnAS as a system -service on Microsoft Windows platforms. This applies starting from JOnAS -3.3.2.
- -This procedure uses ANT targets that are introduced in JOnAS 3.3.2. The -procedure also uses the Java Service Wrapper open source project which must -be downloaded and installed separately.
- -WRAPPER_HOME environment variable to the root
- directory for Java Service Wrapper.
- For example, if the package for Wrapper version 3.0.5 is unzipped into - c:\jsw, then SET WRAPPER_HOME=c:\jsw\wrapper_win32_3.0.5
-Before JOnAS can be run as a WIN32 service, it is necessary to create a -Java Service Wrapper configuration file. Prior to executing the steps in this -section, it is necessary to create a JONAS_BASE directory as described in the -JOnAS Configuration Guide.
--- -The -Djonas.name=<server_name> parameter is optional. If - not specified, the default server name is 'jonas'.
-
-Prior to executing create_win32service it is necessary to -set environment variables as required for JOnAS execution. The values -of the environment variables are saved in the wrapper_ext.conf file -as wrapper properties. -
--* The config_env.bat file is used to configure JDBC drivers -in the CLASSPATH. Any changes to config_env.bat will affect the -CLASSPATH environment variable, and therefore requires that -the wrapper configuration be updated by running -create_win32service. -
-The wrapper configuration must be updated whenever any of these -environment variables are modified. -Refer to the Modify JOnAS -Configuration section for more information.
- - -After the %JONAS_BASE% directory has been updated for use with Java -Service Wrapper, JOnAS can be installed as a WIN32 service using the -install_win32service ant target. Prior to installing the -configuration as a WIN32 service, the configuration can be tested as a -standard console application. Refer to the -Testing configuration section for more -information. The following steps will install the service.
-By default, the service is configured to start automatically each time -Windows starts. If the administrator would prefer to start the service -manually, modify the wrapper.ntservice.starttype parameter in the -%JONAS_BASE%\conf\wrapper.conf file. Set the value as described in the -comments found in the wrapper.conf file.
- -When it is no longer desirable to run JOnAS as a Windows service, the -service can be uninstalled using the uninstall_win32service ant -target.
-To start the JOnAS service, open the Service Control Manager (Control -Panel Services) window, select the JOnAS service and start the service. -As an alternative, the service may be started from a DOS command window -using the jonas ntservice start command.
- -By default, JOnAS will be started automatically each time Windows is -started. After installing the service, it can be started manually to avoid -the need to reboot Windows.
- -NOTE: -Any environment variables referenced within either of the -wrapper.conf and wrapper_ext.conf files must be defined as system -environment variables. -
- -To stop the JOnAS service, open the Service Control Manager window, select -the JOnAS service and stop the service. As an alternative, the service may be stopped -from a DOS command window using the -jonas ntservice stop command.
- -The status of the JOnAS service may be obtained from a DOS command window using the -jonas ntservice status command.
- -The create_win32service ant target copies files from -the Java Service Wrapper installation directory and generates a configuration -file in the %JONAS_BASE% directory. The following files are managed by the -create_win32service ant target.
-* wrapper.conf contains Java Service Wrapper -configuration properties. This file is copied to the conf directory -by the CREATE_JONASBASE command. Changes made to this file are -not affected by subsequent execution of the create_win32service target.
-** wrapper_ext.conf contains Java Service Wrapper -configuration properties specific to the JOnAS service. This file is -generated by the create_win32service ant target. Any changes made to -this file will be lost when the create_win32service target is -executed.
- -In addition to the files located in the conf directory, JOnAS -configuration is affected by the contents of -%JONAS_ROOT%\bin\nt\config_env.bat, and by the following environment variables, -CLASSPATH, JAVA_OPTS, JONAS_OPTS, TOMCAT_OPTS, JETTY_OPTS. -If changes are made to config_env.bat, or any of these -environment variables, it is necessary to update the -Java Service Wrapper configuration files.
--JOnAS memory usage is controlled by the -Xms and -Xms JVM arguments. Prior -to running create_win32service, set the JAVA_OPTS environment variable with -the desired values for -Xms and -Xmx. The create_win32service target will -generate these values as wrapper.java.additional parameters in the -wrapper_ext.conf file. -
-jonas ntservice stop command line.config_env.bat, and the
- CLASSPATH, JAVA_OPTS, JONAS_OPTS, TOMCAT_OPTS, JETTY_OPTS
- environment variables as needed.-Note: Changes to the JOnAS configuration files located in the -%JONAS_BASE%\conf directory do not affect the contents of the -wrapper_ext.conf file. When making changes to the files located in the -conf directroy, it is only necessary to stop the service and restart -the service for the changes to take effect. -
- - -After the Java Service Wrapper configuration files have been generated, it -is possible to test the configuration in a console window before installing -the configuration as a WIN32 service.
-The Java Service Wrapper will start as a console application and load -JOnAS using the configuration generated by the create_win32service -ant target.
- -Note that this test procedure is using environment variables that -are set for the current user. Verify that any environment -variables used in the wrapper.conf and/or wrapper_ext.conf files -are also set as system environment variables. -- -
Enter CTRL-C to terminate JOnAS. After pressing Ctrl-C, the -Java Service Wrapper displays the following messages to the execution report, -and/or log file.
-wrapper | CTRL-C trapped. Shutting down.
-jvm 1 | 2003-12-02 15:25:20,578 : AbsJWebContainerServiceImpl.unRegisterWar
- : War /G:/w32svc/webapps/autoload/ctxroot.war no longer available
-jvm 1 | Stopping service Tomcat-JOnAS.
-wrapper | JVM exited unexpectedly while stopping the application.
-wrapper | <-- Wrapper Stopped.
-
-
diff --git a/jonas_doc/olddoc/howto/clusterdetails/AutomaticClusterConfiguration.html b/jonas_doc/olddoc/howto/clusterdetails/AutomaticClusterConfiguration.html
deleted file mode 100644
index d62d88f8b79dfba580e1e44bcb1b3d292db67d93..0000000000000000000000000000000000000000
--- a/jonas_doc/olddoc/howto/clusterdetails/AutomaticClusterConfiguration.html
+++ /dev/null
@@ -1,181 +0,0 @@
-
-
-
-
-
-
- newjc is a tool included in
- JOnAS that constructs and configures the JOnAS bases (JOnAS
- instances) for the cluster. It also creates the configuration
- files needed for mod_jk.
-This tool is located under
-$JONAS_ROOT/examples/sampleCluster2/newjc.
newjc can be used to configure cluster configurations other than -sampleCluster2. These configuration files are basic and can -be edited as needed to fit site requirements.
-newjc can customize some of the characteristics of the cluster through -the build-jc.properties, build-db.properties, build-master.properties and jonas-newjc.properties files.
-The default configuration is located at -$JONAS_ROOT/examples/sampleCluster2/newjc/build-jc.properties. This -file should not require modifications for sampleCluster2, unless there -are port conflicts. Port assignments for sampleCluster2 are -also summarized in -$JONAS_ROOT/examples/sampleCluster2/PortConfiguration.txt. This -file is for documentation only and is not used by newjc.
-Before newjc is run for the first time on Linux, create -the following directory: $HOME/jc.config/lib
-mkdir –p $HOME/jc.config/lib
-Run newjc.
-cd $JONAS_ROOT/examples/sampleCluster2/newjc
-./newjc.sh
-Here is an example output. Script output is in gray. User inputs are black -and bold.
-------Buildfile: ./build-jc.xml
-init:
-create_jonas_cluster:
-[input] Choose your output directory : -[default : ${myenv.JONAS_BASE}] :
-/home/<user>/cluster
-[input] Choose your prefix for the JONAS_BASE -directories : [default : jb] :
-jb
-[input] Choose your protocol : [default : -cmi] :(jrmp,jeremie,iiop,cmi,)
-cmi
-[input] Choose your database : [default : -hsql] :
-hsql
-[input] Choose your WebContainer : [default : -tomcat] :(tomcat,)
-tomcat
-[input] Choose your cluster architecture -[bothWebEjb/diffWebEjb] : [default : diffWebEjb] :(bothWebEjb,diffWebEjb,)
-diffWebEjb
-[input] Choose the number of web instances : -[default : 2] :
-2
-[input] Choose the number of ejb instances : -[default : 2] :
-2
-
/// newjc output deleted for brevity
-Files created by newjc will be discussed in the following -section.
-Note: On Windows the steps are the same, except,
-create the folder C:\Documents and -Settings\<user>\jc.config\lib
-Run the newjc.cmd
-For more information about newjc refer -to the ObjectWeb site.
-- -
Newjc created tomcat_jk.conf
-and
-workers.properties files. For sampleCluster2 they are located in
-/home/<user>/cluster/conf/jk.
-The #Web section of build-jc.properties defines configuration
-parameters set in these files by newjc.
-Refer to -workers how to documentation on the Tomcat site.
-
-tomcat_jk.conf contains apache directives supported in
-httpd.conf or apache2.conf. They are isolated in a separate file for modularity,
-then included in
-httpd.conf or apache2.conf.
-
-newjc also generated four JOnAS instances
-(JONAS_BASE) in directories jb1, jb2, jb3 and jb4 under
-/home/<user>/cluster. Configuration files are all in the conf
-directory of each JOnAS instance. The files pertinent to cluster
-are described below.
jb1 and jb2 are sampleCluster2 JOnAS web container instances. jb3 and jb4 are sampleCluster2 JOnAS EJB container instances.
-newjc generated a script (jcl4sc2) for controlling the cluster (start/stop/kill). -
The #Carol section of build-jc.properties defines configuration -parameters set in the carol.propetries file and jgroups-cmi.xml by -newjc.
-This allows JNDI replication to support load balancing at the -EJB level using the CMI protocol.
-Note: The multicast address and port must be identically -configured for all JOnAS/Tomcat instances.
-The #Services section of build-jc.properties defines -configuration parameters set in the jonas.properties file by -newjc.
-The #Web section of build-jc.properties defines some
-configuration parameters set in the server.xml file by newjc.
-In particular, a connector XML element for AJP1.3 protocol is
-defined, as well as a jvmRoute to support load balancing at the
-web level, via this connector.
A Cluster XML element was also added. It defines parameters for -achieving Session replication at the web level with -JOnAS.
-Refer to the AJP -Connector and the -Engine Container documentation.
-Note: The jvmRoute name generated by newjc is the -same as the name of the associated worker defined in -worker.properties. This will ensure the Session -affinity.
-These files are scripts to run the sampleCluster2 cluster on Linux and Windows.
- - - -To make apache aware of this new file, edit <prefix>/conf/httpd.conf.-Include -conf/jk/tomcat_jk.conf
Move the jk directory created by newjc under the APACHE structure:
-<mv /home/<user>/cluster/conf/jk $APACHE_HOME/conf>
Note that some UNIX distributions may locate the module in the -folder libexec instead of the folder modules.
- - - diff --git a/jonas_doc/olddoc/howto/clusterdetails/ManualClusterConfiguration.html b/jonas_doc/olddoc/howto/clusterdetails/ManualClusterConfiguration.html deleted file mode 100644 index 1433613ab44bde9b64a990d2e00f39e6fbf6e374..0000000000000000000000000000000000000000 --- a/jonas_doc/olddoc/howto/clusterdetails/ManualClusterConfiguration.html +++ /dev/null @@ -1,403 +0,0 @@ - - - - - - --Load-balancing at the web level with mod_jk
--Configure HTTP session replication with Tomcat
- --CMI Configuration (JNDI & EJB load balancing)
- - - -This depends on the distribution being used. Create a file tomcat_jk.conf and workers.properties in "$APACHE_HOME/conf/jk/".
tomcat_jk.conf:
-# Location of the worker file
- JkWorkersFile "conf/jk/workers.properties"
- # Location of the log file
- JkLogFile "conf/jk/mod_jk.log"
- # Log level : debug, info, error or emerg
- JkLogLevel emerg
- # Shared Memory Filename ( Only for Unix platform )
- # required by loadbalancer
- JkShmFile conf/jk/jk.shm
- # Assign specific URL to Tomcat workers
- # A mount point from a context to a Tomcat worker
- JkMount /sampleCluster2 loadbalancer
- JkMount /sampleCluster2/* loadbalancer
- # A mount point to the status worker
- JkMount /jkmanager jkstatus
- JkMount /jkmanager/* jkstatus
- # Enable the Jk manager access only from localhost
- <Location /jkmanager/>
- JkMount jkstatus
- Order deny,allow
- Deny from all
- Allow from 127.0.0.1
- </Location>
-
The following is an example of a workers.properties file:
# List the workers' names
- worker.list=loadbalancer,jkstatus
- # ----------------
- # First worker
- # ----------------
- worker.worker1.port=9010
- worker.worker1.host=server1
- worker.worker1.type=ajp13
- # Load balance factor
- worker.worker1.lbfactor=1
- # Define preferred failover node for worker 1
- #worker.worker1.redirect=worker2
- # ----------------
- # Second worker
- # ----------------
- worker.worker2.port=9011
- worker.worker2.host=server2
- worker.worker2.type=ajp13
- worker.worker2.lbfactor=1
- # Disable worker2 for all requests except failover
- #worker.worker2.disabled=True
- # ----------------------
- # Load Balancer worker
- # ----------------------
- worker.loadbalancer.type=lb
- worker.loadbalancer.balanced_workers=worker1,worker2
- #Specifies whether requests with session's id should be routed to the same worker
- #worker.loadbalancer.sticky_session=false
- # ----------------------
- # jkstatus worker
- # ----------------------
- worker.jkstatus.type=status
-
| Explanations: | |
| port: | Port number of the remote Tomcat instance listening for defined protocol requests |
| host: | Host name or IP address of the backend JOnAS/Tomcat node. - Can be set to localhost when the cluster members are collocated to a single machine. |
| type: | Type of the worker (can be one of ajp13, ajp14, jni, status or lb) |
| The status worker makes it possible to manage loadbalancing parameters and status through a web interface. In the above example, use URL http://localhost/jkmanager | |
| lbfactor: | An integer number indicating how much a worker has to work |
| example: - worker1.lbfactor = 2 - worker2.lbfactor = 1 - worker1 receives 2 times more requests than worker2 | |
| sticky_session: | - Round robin where the mod_jk sends the request to a server. When session replication is activated in JOnAS, the session will not be lost. |
| redirect: | worker name to use when the current worker is in error state |
| disabled: | True/False - default status of the current worker |
| The redirect/disabled parameters make it possible to define a failover configuration between 2 workers. In the above example, the lb redirects the requests to worker 2 if worker 1 is in error state. In other cases, worker 2 will not receive any requests, thus acting as a hot standby. | |
Note: Refer to the workers.properties and workers howto documentation.
- -Other possible mod_jk configurations (includes mod_jk2, mod_jk, migration mod_jk2 to mod_jk)
- Attention: mod_jk2 is deprecated.
-
- This depends on the distribution being used. Here apache 2 is assumed and it is considered
- that mod_jk.so is available.
-
- # Include the user configurations:
- Include conf/jk/tomcat_jk.conf
-
<!-- Define an AJP 1.3 Connector on port 9010 -->
- <Connector
-
- port="9010" minProcessors="5"
- maxProcessors="75"
- acceptCount="10" debug="20" protocol="AJP/1.3"/>
-
| Explanations: | |
| port: | -The TCP port number on which this Connector will create a server socket and await incoming connections. | -
| minProcessor: | -The minimum number of processors to start at intialization time. If not specified, this attribute is set to 5. | -
| maxProcessor: | -The maximum number of processors allowed. | -
| acceptCount: | -The maximum queue length for incoming connection requests when all possible requests processing threads are in use. Any requests received when the queue is full will be refused. - | -
| debug: | -The debugging detail level of log messages generated by this component, with higher numbers creating more detailed output. | -
| protocol: | -This attribute must be AJP/1.3 to use the AJP handler. | -
Note: Refer to the AJP Connector documentation. -
-| Explanations: | |
| name: | -Logical name of this Engine, used in log and error messages | -
| jvmRoute: | -Uniquely identifies the Tomcat server to the Apache server - Name has been specified in workers.properties - |
-
| defaultHost: | -Identifies the Host that will process requests directed to host names on this server | -
| debug: | -The level of debugging detail logged by this Engine | -
Note: The jvmRoute name should be the same as the name of the
- associated worker defined in workers.properties. This will ensure the
- Session affinity.
-
- Refer to the Engine Container documentation.
- <Cluster className="org.apache.catalina.cluster.tcp.SimpleTcpCluster" - clusterName="myTomcatCluster" - managerClassName="org.apache.catalina.cluster.session.DeltaManager" - expireSessionsOnShutdown="false" - useDirtyFlag="true"> - <Membership - className="org.apache.catalina.cluster.mcast.McastService" - mcastAddr="228.0.0.4" - mcastPort="45564" - mcastFrequency="500" - mcastDropTime="3000" - debug = "9" - /> - <Receiver - className="org.apache.catalina.cluster.tcp.ReplicationListener" - tcpListenAddress="auto" - tcpListenPort="4001" - tcpSelectorTimeout="100" - tcpThreadCount="6" - /> - - <Sender - className="org.apache.catalina.cluster.tcp.ReplicationTransmitter" - replicationMode="pooled" - /> - - <Valve className="org.apache.catalina.cluster.tcp.ReplicationValve" - filter=".*\.gif;.*\.js;.*\.jpg;.*\.htm;.*\.html;.*\.txt;" - /> - - <Deployer className="org.apache.catalina.cluster.deploy.FarmWarDeployer" - tempDir="/tmp/war-temp/" - deployDir="/tmp/war-deploy/" - watchDir="/tmp/war-listen/" - watchEnabled="false" - /> - </Cluster>
Note1: The multicast address and multicast port of the Membership element must be identically configured - for all JOnAS/Tomcat instances.
-Note2: When the nodes are collocated to the same machine, the tcpListenPort of the Receiver element must - be unique per JOnAS/Tomcat instance.
-Note: More detailed information is available in the CMI guide .
- -In the case of EJB level clustering (CMI), the client may be either a fat -Java client (e.g., a Swing application), or a Web application (i.e., -Servlets/JSPs running within JOnAS). In the second case, the JOnAS server -running the Web client should be configured in the same way as the other -nodes of the cluster.
-build.properties of the application, set the protocol name to
- cmi before compilation: $JONAS_BASE/conf/carol.properties of each server (in the directory
- $JONAS_BASE/conf) and of a fat Java client, set the protocol to cmi: $JONAS_BASE/conf/carol.properties of each server of the cluster, configure
- the url, the jgroups stack, the jgroups group name and the round-robin weight factor,
- etc. carol.properties file: $JONAS_BASE/conf/jgroups-cmi.xml.
- It describes the protocols list and their parameters, e.g., the UDP protocol contains
- the multicast address parameter. UDP protocol is set by default and can be changed
- dynamically.
- Note 1: The multicast address and port defined in the $JONAS_BASE/conf/jgroups-cmi.xml
-and the group name defined in the $JONAS_BASE/conf/carol.properties file must be the same for all
-JOnAS nodes in the cluster.
Note 2: If Tomcat Replication associated to cmi is used, the multicast -addresses of the two configurations must be different. Same requirement for -the EJB high availability configuration.
- -Note 3: If the cluster is defined across several machines, the CMI url has to be set with the real ip -address or ip alias and not the loopback address.Otherwise, the EJBs won't be reachable from the remote machines.
- -This section describes how to enable the EJB replication framework (SFSB).
-
- # Set the ha service
- jonas.services registry,jmx,jtm,db,security,resource,ejb,ws,web,ear,ha,discovery
-
- # Set the name of the implementation class of the HA service.
- jonas.service.ha.class org.objectweb.jonas.ha.HaServiceImpl
-
- # Set the group communication framework to use
- jonas.service.ha.gcl jgroups
-
- # Set the JGroups configuration file name
- jonas.service.ha.jgroups.conf jgroups-ha.xml
-
- # Set the JGroups group name
- jonas.service.ha.jgroups.groupname jonas-rep
-
- # Set the SFSB backup info timeout. The info stored in the backup node is
# removed when the timer expires.
- jonas.service.ha.timeout 600
-
- # Set the datasource for the tx table
- jonas.service.ha.datasource jdbc_1
-
- create TABLE ha_transactions (txid varchar(60));
-
- <jonas-session>
- <ejb-name>DummySFSB</ejb-name>
- <jndi-name>DummySFSB</jndi-name>
- ...
- <cluster-replicated>true</cluster-replicated>
- <cluster-home-distributor>Dummy_HomeDistributor.vm</cluster-home-distributor>
- <cluster-remote-distributor>Dummy_RemoteDistributor.vm</cluster-remote-distributor>
- </jonas-session>
-
Sample C-JDBC DataSource configuration file to use in JOnAS:
--###################### C-JDBC DataSource configuration example -# -##### -#DataSource configuration -# -#datasource.name jdbc_1 -datasource.url jdbc:cjdbc://localhost:25322/myDB -datasource.classname org.objectweb.cjdbc.driver.Driver -datasource.username user -datasource.password pass -# WARNING: you must specify the mapper of the databases used as -# backend by C-JDBC. It is not possible to use a heterogenious c-jdbc -# configuration here. -datasource.mapper rdb.hsql --
1. Edit the file $JONAS_BASE/conf/server.xml; locate and uncomment
-the
-following line:
-
<!--- Change it to look like the following:
<Connector port="9009"
enableLookups="false" redirectPort="9043" debug="0"
protocol="AJP/1.3" />
-->
<Connector port="9009"
enableLookups="false" redirectPort="9043" debug="0"
protocol="AJP/1.3" />
- Replace the base Engine tag in which a jvmRoute -with the standard engine is used.
...
<Connector className="org.apache.coyote.tomcat5.CoyoteConnector"
port="9009" minProcessors="5" maxProcessors="75"
enableLookups="true" redirectPort="9043"
acceptCount="10" debug="0" connectionTimeout="0"
useURIValidationHack="false"
protocolHandlerClassName="org.apache.jk.server.JkCoyoteHandler"/>
<Engine name="Tomcat-JOnAS-Engine" defaultHost="localhost" debug="0"
jvmRoute="jonas01">
- and uncomment the following line: <Engine name="Tomcat-JOnAS-Engine" defaultHost="localhost" debug="0">
-- -Note: Always -backup files like server.xml before editing.
<Listener className="org.apache.jk.config.ApacheConfig"-
modJk="$APACHE_HOME/modules/mod_jk.so" />
<Listener className="org.apache.jk.config.ApacheConfig"- When jonas/tomcat is restarted, there will be - a file created under
append="true" forwardAll="false"
modJk="$APACHE_HOME/modules/mod_jk.so"/>
-
# Load the mod_jk module if not loaded.
<IfModule !mod_jk.c>
LoadModule jk_module "$APACHE_HOME/modules/mod_jk.so"
</IfModule>
# Specify location of worker file and log file. Worker file will follow shortly.
JkWorkersFile "$JONAS_BASE/conf/jk/workers.properties"
JkLogFile "$JONAS_BASE/logs/mod_jk.log"
# When and how much logging.
JkLogLevel emerg
# This is a little awkward. It seems mod_jk associates applications it will
# map to tomcat based on the virtual host. If for instance I wish to visit
# the jonasAdmin application through http://jonas-server/jonasAdmin from another
# machine and I have the following setting then the application behaves
# perfectly normally, i.e, behaves as one would expect if you
# were using the application directly using the appropriate port (9000).
# However, if you try using http://localhost/jonasAdmin from jonas-server
# without the explicit VirtualHost declaration, only the directory contents
# are mapped. No processing on the tomcat is carried out, so struts based
# applications will fail to work. That is the reason why we explicitly
# mention both virtual hosts.
<VirtualHost jonas-server>
ServerName jonas-server
JkMount /cmp2 ajp13
JkMount /cmp2/* ajp13
JkMount /alarm ajp13
JkMount /alarm/* ajp1
JkMount /earsample ajp13
JkMount /earsample/* ajp13
JkMount /jonasAdmin ajp13
JkMount /jonasAdmin/* ajp13
</VirtualHost>
<VirtualHost localhost>
ServerName localhost
JkMount /cmp2 ajp13
JkMount /cmp2/* ajp13
JkMount /alarm ajp13
JkMount /alarm/* ajp13
JkMount /earsample ajp13
JkMount /earsample/* ajp13
JkMount /jonasAdmin ajp13
JkMount /jonasAdmin/* ajp13
</VirtualHost>
-3. Now tell apache to use this file. Backup the -file: $APACHE_HOME/conf/httpd.conf.
Include ${JONAS_BASE}/conf/jk/mod_jk.conf
- Note: replace ${JONAS_BASE} with
-appropriate value.LoadModule jk2_module modules/mod_jk2.so-
-
# workers.java_home should point to your Java installation. Normally
# you should have a bin and lib directories beneath it.
#
workers.java_home=/usr/lib/jvm/java
#
# You should configure your environment slash... ps=\ on NT and / on UNIX
# and maybe something different elsewhere.
#
ps=/
#
#------ ADVANCED MODE ------------------------------------------------
#---------------------------------------------------------------------
#
#
#------ DEFAULT worket list ------------------------------------------
#---------------------------------------------------------------------
#
#
# The workers that your plugins should create and work with
#
# Add 'inprocess' if you want JNI connector
worker.list=ajp13
# , inprocess
#
#------ DEFAULT worker1 WORKER DEFINITION ------------------------------
#---------------------------------------------------------------------
#
#
# Defining a worker named worker1 and of type worker1
# Note that the name and the type do not have to match.
#
worker.ajp13.port=9009
worker.ajp13.host=jonas-server
worker.ajp13.type=ajp13
#----------------------------------------------------------
- - diff --git a/jonas_doc/olddoc/howto/clusterdetails/mod_jk2_embeddedtomcat.html b/jonas_doc/olddoc/howto/clusterdetails/mod_jk2_embeddedtomcat.html deleted file mode 100644 index 6dc24964316f726e66d88619735d01046c5a7fd1..0000000000000000000000000000000000000000 --- a/jonas_doc/olddoc/howto/clusterdetails/mod_jk2_embeddedtomcat.html +++ /dev/null @@ -1,176 +0,0 @@ - - - - - - -
1. Backup /$APACHE_HOME/conf/httpd.conf:
-
-cp
-$APACHE_HOME/conf/httpd.conf $APACHE_HOME/conf/httpd.conf.backup
2. Edit (~line 208) httpd.conf to add the loading of mod_jk2.so:
-
-# Adding jk2_module reference.
-LoadModule jk2_module modules/mod_jk2.so
-
-
3. Edit $APACHE_HOME/conf.d/JOnAS.conf
-with the following content:
-
-Alias /docs/jonas "$JONAS_BASE/doc/jonas-4.1.2"
-<Directory "$JONAS_BASE/doc/jonas-4.1.2">
- Options Indexes MultiViews
- AllowOverride None
- Order allow,deny
- Allow from all
-</Directory>
-
-Alias /webapps/jonas "$JONAS_BASE/webapps/jonas"
-<Directory "$JONAS_BASE/webapps/jonas">
- Options Indexes MultiViews
- AllowOverride None
- Order allow,deny
- Allow from all
-</Directory>
-
-<IfModule mod_jk2.c>
-
-<Location /earsample>
- JkUriSet group jonas
-</Location>
-
-<Location /jonasAdmin>
- JkUriSet group jonas
-</Location>
-
-<Location /cmp2>
- JkUriSet group jonas
-</Location>
-
-<Location /alarm>
- JkUriSet group jonas
-</Location>
-
-</IfModule>
-
-
4. Edit/create $APACHE_HOME/conf/workers2.properties
-with the following content:
-
-[logger]
-level=DEBUG
-
-
-# Shared memory handling. Needs to be set.
-[shm]
-info=Scoreboard. Required for reconfiguration and status with
-multiprocess servers
-file=$APACHE_HOME/logs/jk2.shm
-size=1048576
-debug=0
-disabled=0
-
-
-# The channel configuration shall be consistent with
-# the configuration of JOnAS in server.xml
-# port = port of the AJP (jk2) connector
-# tomcatId = jvmRoute attribute of the <Engine> element
-[channel.socket:toJonas01]
-info=channel to a JOnAS instance - tomcatId shall be identical to
-jvmRoute in the server.xml file of the JOnAS instance
-host=localhost
-port=9009
-group=jonas
-
-
-[status:status]
-info=provides info on the connecteur usage
-
-
-[uri:$/jkstatus*]
-info=get the connector usage info at /jkstatus
-group=status:status
-
-...
-
-<Connector className="org.apache.coyote.tomcat5.CoyoteConnector"
-
-port="9009" minProcessors="5" maxProcessors="75"
-
-enableLookups="true" redirectPort="9043"
-
-acceptCount="10" debug="0" connectionTimeout="0"
-
-useURIValidationHack="false"
-
-
-protocolHandlerClassName="org.apache.jk.server.JkCoyoteHandler"/>
-...
-<Engine name="Tomcat-JOnAS-Engine" defaultHost="localhost" debug="0"
-jvmRoute="jonas01">
-
-
8. Deploy cmp2.ear and alarm.ear.
-
9. Those apps are available at:
-
-http://<hostname>/cmp2
-http://<hostname>/earsample
-http://<hostname>/alarm
-http://<hostname>/jonasAdmin
-
1. Open the file $JONAS_BASE/conf/server.xml and uncomment the
-following line:
-
<!---
<Connector port="9009"
enableLookups="false" redirectPort="9043" debug="0"
protocol="AJP/1.3" />
-->
Edit it to look like the following:
-
<Connector port="9009"-2. Now you can -either let tomcat generate the mod_jk.conf file automatically,
enableLookups="false" redirectPort="9043" debug="0"
protocol="AJP/1.3" />
<Listener className="org.apache.jk.config.ApacheConfig"-
modJk="$APACHE_HOME/modules/mod_jk.so" />
<Listener className="org.apache.jk.config.ApacheConfig"- When jonas/tomcat is restarted, there will be a file -created under $JONAS_BASE/conf/auto called mod_jk.conf.
append="true" forwardAll="false"
modJk="$APACHE_HOME/modules/mod_jk.so"/>
-b) If you want to create a custom file, the recommendation is to place -mod_jk.conf under $JONAS_BASE/conf/jk.
# Load the mod_jk module if not loaded.-
<IfModule !mod_jk.c>
LoadModule jk_module "$APACHE_HOME/modules/mod_jk.so"
</IfModule>
# Specify location of worker file and log file. Worker file will follow shortly.
JkWorkersFile "$JONAS_BASE/conf/jk/workers.properties"
JkLogFile "$JONAS_BASE/logs/mod_jk.log"
# When and how much logging.
JkLogLevel emerg
# This is a little awkward. It seems mod_jk associates applications it will
# map to tomcat based on the virtual host. If for instance I wish to visit
# the jonasAdmin application through http://jonas-server/jonasAdmin from another
# machine and I have the following setting then the application behaves
# perfectly normally, i.e, struts kicks in as expected, form based
# authentication and forwarding is done exactly as one would expect if you
# were using the application directly using the appropriate port (9000).
# However, if you try using http://localhost/jonasAdmin from jonas-server
# without the explicit VirtualHost declaration, only the directory contents
# are mapped. So we need to explicitly mention both virtual hosts.
<VirtualHost jonas-server>
ServerName jonas-server
JkMount /olstore ajp13
JkMount /olstore/* ajp13
JkMount /jonasAdmin ajp13
JkMount /jonasAdmin/* ajp13
</VirtualHost>
# ajp13 is infact the worker name used in workers.properties.
<VirtualHost localhost>
ServerName localhost
JkMount /olstore ajp13
JkMount /olstore/* ajp13
JkMount /jonasAdmin ajp13
JkMount /jonasAdmin/* ajp13
</VirtualHost>
3. To tell apache to use this file, edit the
-$APACHE_HOME/conf/httpd.conf file and insert:
-
Include ${JONAS_BASE}/conf/jk/mod_jk.conf
-Note: Replace ${JONAS_BASE} with appropriate value.4. Create
-a workers.properties file. This can be placed in
-
$JONAS_ROOT/conf/jk/workers.properties-A sample that has been used successfully is:
# workers.java_home should point to your Java installation. Normally-
# you should have a bin and lib directories beneath it.
#
workers.java_home=/usr/lib/jvm/java
#
# You should configure your environment slash... ps=\ on NT and / on UNIX
# and possibly something different elsewhere.
#
ps=/
#
#------ ADVANCED MODE ------------------------------------------------
#---------------------------------------------------------------------
#
#
#------ DEFAULT worket list ------------------------------------------
#---------------------------------------------------------------------
#
#
# The workers that your plugins should create and work with
#
# Add 'inprocess' if you want JNI connector
worker.list=ajp13
# , inprocess
#
#------ DEFAULT worker1 WORKER DEFINITION ------------------------------
#---------------------------------------------------------------------
#
#
# Defining a worker named worker1 and of type worker1
# Note that the name and the type do not have to match.
#
worker.ajp13.port=9009
worker.ajp13.host=jonas-server
worker.ajp13.type=ajp13
#----------------------------------------------------------
Sequoia is a transparent middleware solution for offering clustering, load balancing and failover services for any database. The purpose of this howto is to explain how to setup a Sequoia database cluster with JOnAS, and more precisely a RAIDB1 cluster composed of three HSQLDB databases and one Sequoia controller. This configuration allows to replicate the data in two different databases. The third database is used as recovery log. For further informaton about Sequoia and its configuration, please refer to the Sequoia documentation.
- -Download the Sequoia binaries from the Sequoia site.
-Extract the Sequoia archive in a folder. For instance:
-tar xvfz sequoia-x.y-bin.tar.gz
Set the environment variables.
-export JAVA_HOME=<Path to JDK home>
-export SEQUOIA_HOME=<Path to the Sequoia home>
Modify the $SEQUOIA_HOME/demo/demo-raidb1.sh file.
-The ports for the HSQLDB instances must be modified to match the sampleCluster2 configuration. Change the ports for the three databases to 11001, 11002, 11003.
Modify the Sequoia virtual database file: $SEQUOIA_HOME/config/virtualdatabase/hsqldb-raidb1.xml
-Change the ports according to the values defined in the section above. To avoid problems in the Datasource configuration of JOnAS, modify also the password for the user to log in (VirtualLogin element). Warning if you choose another username than default value (user), modify also the vLogin attribute of ConnectionManager elements.
Start the cluster (HSQLDB instances and then Sequoia controller).
-$SEQUOIA_HOME/demo/demo-raidb1.sh
-
Connect to the Sequoia controller using the $SEQUOIA_HOME/drivers/sequoia-driver.jar JDBC driver and the URL:
-jdbc:sequoia://localhost:25322/myDB with username: <user> and password: <pass>
-Use the password you set in $CJDBC_HOME/config/virtualdatabase/hsqldb-raidb1.xml file.
Sample Sequoia DataSource configuration file to use in JOnAS:
--###################### Sequoia DataSource configuration example -# -##### -DataSource configuration -# -datasource.name jdbc_1 -datasource.url jdbc:sequoia://localhost:25322/myDB -datasource.classname org.continuent.sequoia.driver.Driver -datasource.username user -datasource.password pass -# WARNING: you must specify the mapper of the databases used as -# backend by Sequoia. It is not possible to use a heterogenious -# Sequoia configuration here. -datasource.mapper rdb.hsql --