![]() | ![]() | ![]() | ![]() | ![]() | ![]() | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() | ![]() | ![]() | ![]() | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() | ![]() | ![]() | ![]() | ![]() | ![]() | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() | ![]()
![]() ![]() |
1 ![]() 2 ![]() 3 ![]() 4 ![]() 5 ![]() 6 ![]() 7 ![]() AbstractThis an advanced document and is not aimed begining or intermediate OpenEJB users. OpenEJB users should be able to configure any JDBC datasource using the built in JDBC Connector that ships with OpenEJB. To learn how to configure a JDBC datasource. follow this link. The aim of this document is to show OpenEJB architects what needs to be done in order to deploy a J2EE Connector service in OpenEJB. The J2EE Connector Architecture allows virtually any type of connection-oriented resource to be plugged into a J2EE compliant container. As mentioned, OpenEJB already comes with a JDBC connector, but other implementations are possible such as a JavaMail connector or a Java Message Service (JMS) connector. The goal of the OpenEJB Service Architecture is to make the lives of users much easier. With the services packaged into jars, each with their own service-jar.xml, it is possible to package and deploy services like components, just as you can with EJBs. Each service-jar.xml is synonymous to the ejb-jar.xml of a set of EJBs. It contains all the information needed for OpenEJB to load and use the service. It also contains the default configurations of all the services in the jar so that they can be simply dropped in and ran out-of-the-box. It is possible to plug-in other types of services, such as new containers, but this document uses a sample connector service to illustrate the ins and outs of creating and deploying a custom service into OpenEJB. Firstly, we take a deeper look at how OpenEJB configuration file -- openejb.conf -- looks like. It is strongly encouraged to read the Configure the data source section in Hello OpenEJB World! - A basic CMP entity bean example as you can find an introduction to it over there. Having done that, we move on to discussing different types of OpenEJB services. One type is playing a great role in our example - the connector service. To develop our custom service we leverage what is already provided in OpenEJB - the existing "Default JDBC Service". We don't want to reinvent the wheel, do we ? So, we, real Java programmers, will subclass the service's class to give you an insight on how to introduce a new functionality in the already existing OpenEJB services. Perhaps, some time you will create a brand new production-ready service for OpenEJB. That would be great. The last section tests it out with the CMP example from Hello OpenEJB World! - A basic CMP entity bean example. We shall see two services on the list of the services to choose from while deploying the bean -- one of them will be our newly created JDBC connector service. Introduction to OpenEJB servicesHere is a part of OpenEJB configuration file's XML Schema. An XML Schema is like a DTD, but capable of doing much more validation than a DTD. It shows the root element of the configuration file OpenEJB will read at startup.
As you can see there are 9 different elements OpenEJB configuration file can use. 7 of them represent service-specific elements -- more about those later. Some of them may appear more than once (e.g. Connector) and some at least once (e.g. SecurityService). The document will cover the basics about the Connector service type. So, let's enter the scene by examining the Connector element. Here is OpenEJB's XML Schema part of the element:
As the above XML Schema shows the Connector element in OpenEJB configuration file must consist of at least one attribute id. The id attribute is in fact a stringified pointer to the appropriate declaration in one of the deployed services' configuration. Strictly speaking, it is the name which must appear in a service's deployment descriptor - we will talk about it later.
The another attribute - jar - is exactly the path to the jar file
where OpenEJB expects to find the service's deployment descriptor (with
the id name) and classes as well as other resources required by the
service. The service's deployment descriptor is an XML file which is
required to be available at the following paths within the service's jar
file:
In its simplest form the deployment descriptor would look like as follows:
Here is a description of the simplest deployment descriptor's elements and
attributes:
OpenEJB comes with several services available. Here is the list of the
services' ids (stringified identifiers) with their short description:
Developing a serviceAfter the introductory material let's delve our hands into the real stuff -- programming. The following steps will lead you through the bumpy road of OpenEJB services programming making it easy like never before. The service you are about to create is a Connector service named "PostgreSQL 7.2.1 Database". The purpose of the service is to carry out our custom name (so we could name it as we want), handle an additional service-specific parameter and finally refuse to connect to other databases than PostgreSQL unless the parameter mandates otherwise. Quite enough as a starter -- after all, this was meant to be a basic service example. So, let's name our brand new service "PostgreSQL 7.2.1 Database". As it has been described in the previous section, the name shall appear in the service's deployment descriptor in META-INF/service-jar.xml. It is simply a value of the id attribute of the ServiceProvider's element. The service's functionality is to provide PostgreSQL connections. It does represent a Connector service; thus, the provider-type is "Connector". The last attribute to assign a value to is class-name. The class must reflect the functionality OpenEJB expects from connectors, i.e. it must implement javax.resource.spi.ManagedConnectionFactory class. Our class extends the already available OpenEJB class - org.openejb.resource.jdbc.JdbcManagedConnectionFactory, which represents "Default JDBC Database" service. All the text between the <ServiceProvider> and </ServiceProvider> tags of the service's declaration in the service-jar.xml will be intepreted as properties and will be passed into the service by OpenEJB as an instance of java.util.Properties when OpenEJB starts up. Service providers should use this area to set default values for all the configurable properties the service has. The format of the text between the <ServiceProvider> and </ServiceProvider> tags can be any text valid for a Java propeties file. The properties themselves can be anything that the Service provider wants. Users can easily reconfigure the service by specifying new values for the properties in the openejb.conf. This overrides the properties in the service's service-jar.xml and allows users to reconfigure the service without having to mess with the service's jar and service-jar.xml file. In the case of our Connector, users can override the default property values we set in our service-jar.xml by going to the <Connector> and </Connector> tags in their openejb.conf file and typing in new properties and values.
An elegant aspect of this approach is that users can create as many
"profiles" or configurations of OpenEJB and it's services by simply
creating an openejb.conf file for each. For example, a user might have
the following config files in their conf/ directory:
Create the directory where the service's files are located. C:\> mkdir C:\my\app\org\acme\service\connectorC:\> cd C:\my\app In your favorite editor, create the file below.
In your favorite editor, create the file below.
Packaging a serviceThis step boils down to compiling the class and creating the jar file using the following commands: C:\my\app> set CP=%OPENEJB_HOME%\lib\ejb-2.0.jarC:\my\app> set CP=%CP%;%OPENEJB_HOME%\lib\jaas_1.0.jar C:\my\app> set CP=%CP%;%OPENEJB_HOME%\lib\jca_1.0.jar C:\my\app> set CP=%CP%;%OPENEJB_HOME%\dist\openejb-0.8.1.jar C:\my\app> javac -d . -classpath %CP% org\acme\service\connector\*.java C:\my\app> jar -cvf postgresql-service.jar org\acme\service\connector\*.class META-INF Deploying a serviceBefore using a service in OpenEJB it has to be deployed first. The process involves modyfing OpenEJB configuration file, i.e. openejb.conf. The following file is the one being used in Configure the data source section in Hello OpenEJB World! - A basic CMP entity bean example with the necessary changes pertaining to our service (note the id attribute has changed as well as the jar attribute and struct parameters have been added). Create the file in the conf directory. C:\my\app> mkdir conf In your favorite editor, create the file below.
Using a serviceDepending on the service type its usage may vary. In case of our Connector service, we leverage the sample entity bean described in Hello OpenEJB World! - A basic CMP entity bean example document. The sample needs to have a connector service configured in OpenEJB before being deployed. Our service is an excellent candidate.
While performing this step you ought to see the following output on OpenEJB console:
The above lines, which begin with '+++' are those from the PostgreSQL 7.2.1 Database service. It should get you a feeling on how OpenEJB initializes services, i.e. what service's methods are being invoked upon OpenEJB startup.
What if it didn't workIf you ran into any problems, first check your openejb.log file at %OPENEJB_HOME%\openejb.log. Look for any lines that begin with "WARN", "ERROR", or "FATAL".
There is a list of the most common problems with possible solutions:
Problem: Solution: Add the PostgreSQL JDBC2 driver to OpenEJB's
CLASSPATH. See the Configure the data source section for more details.
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() | ![]() | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() | ![]() | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() |