Entity bean extended deployment descriptor file

When you create a CMP Enterprise beans using either the WebSphere Application Server Toolkit or RAD, the META-INF folder of that bean will have set of files that map fields in the entity bean to columns in the DB. The Map.mapxmi file in the META-INF is WAS Specific

J2EE applicaiton packaging recommendations

Here are some basic rules to consider when packaging an enterprise application:


• The EJB JAR modules and Web WAR modules comprising an application should be packaged together in the same EAR module.


• When a Web module accesses an EJB module, you should not package the EJB interfaces and stubs in the WAR modules. Thanks to the class loading architecture, EJB stubs and interfaces are visible by default to WAR modules.


• Utility classes used by a single Web module should be placed within its WEB-INF/lib folder.


•  Utility classes used by multiple modules within an application should be placed at the root of the EAR file as Utility Projects, so they are accessible both by servlets and EJBs.


• Utility classes used by multiple applications can be placed on a directory referenced through a shared library definition.

Enhanced ear file

The Enhanced EAR is normal J2EE EAR file, but with additional configuration information for resources required by J2EE application.

When an Enhanced EAR is deployed to WebSphere Application Server, WebSphere can automatically configure the resources specified in the Enhanced EAR. This reduces the number of configuration steps required to set up the WebSphere environment to host the application. When an Enhanced EAR is uninstalled, the resources that are defined at the application level scope are removed as well. However, resources defined at a scope other than application level are not removed because they might be in use by other applications Resources created at Application level scope are limited in visibility to only that application.

The supplemental information in an Enhanced EAR is modified by using the WebSphere Enhanced EAR editor, the Deployment tab of the application deployment descriptor in the RAD





When you export any .ear file from either the WAS Admin COnsole or wsadmin script the WAS server will export enhanced ear file for that application. If you open the .ear file you will notice that it has ibmconfig directory under the META-INF directory that has all the configurations required for the .ear file



You can download the sample code from here

File Serving enabled

When dealing with static content (HTML pages, images, style sheets, and so on), you can choose to have these resources served by WebSphere, or have them served by the HTTP server itself.

If you want WebSphere to serve the static content of your application, you must enable file servlet, also known as the file serving servlet or file serving enabler. This servlet serves up any resource file packaged in the WAR file. The File serving enabled attribute is set to true by default. By changing it to false, the Web server plug-in will not send requests for static content to WebSphere, but leave it up to the HTTP server to serve them.

If you want the Web server to serve static content, you can experience better performance than using WebSphere in this instance, because the Web server is serving the content directly. Moreover, a Web server has more customization options than the file servlet can offer.

Once you enable the file serving enabled, you can also set following additional attributes to customize its behavior

• bufferSize: Sets buffer size that is used for serving static files.


• extendedDocumentRoot: Enables you to configure an application with one or more directory paths from which you can serve static files and Java ServerPages (JSP) files. You can use this attribute when an application requires access to files that exist outside of the application Web archive (WAR) directory. For example, if several applications require access to a set of common files, you can place the common files in a directory to which you can link each application as an extended document root directory.Use this attribute in addition to the contextRoot attribute.


• file.serving.patterns.allow: Specifies that only files matching the specified pattern are served.


• file.serving.patterns.deny: Specifies that files that match the specified file pattern are denied

The extendedDocumentRoot can be used to handle some very interesting use cases. Lets assume that you have 2-3 web applications all of them use same JavaScript framework and images. So instead of copying those files in every .war file you can copy them on file system and set it as extendedDocumentRoot.

I tried modifying my web application to try this feature. I did set value of extendedDocumentRoot property to c:/temp/images like this




Now i can access every file in the c:/temp/images folder as if it is in the context root of original web application ex. i had sample.js in c:/temp/images so i can access it by going to http://localhost:9081/webappext/sample.js

You can download the sample code from here

Serve servlet by class name

You can enable "Serve Servlet by classname" feature, Once you do that you can access any servlet in the web application by its class name in addition through the servlet context

I have one com.webspherenotes.webapp.WebAppExtensionServlet servlet in my WebAppExtensionSample.war file and i can access it by going to http://localhost:9081/webappext/servlet/com.webspherenotes.webapp.WebAppExtensionServlet url.

In this the /webappext is the web application context

You can download the sample code from here

Directory browsing enabled

Directory browsing enabled flag is disabled by default. But if you enable it then the websphere application server will display the content of .war file (Excluding the WEB-INF folder) and let you browse through it.

I do have this simple WebAppExtensionSample.war file that has js folder at the root level, which has one .js file. I enabled the directory browsing and then i went to the web application context root and this is what i see



Make sure that you disable this feature before deploying your application in production

You can download the sample code from here

Web Application Extensions

WebSphere Application Server provides multiple extensions for Web Modules. To work with these extensions open the Web deployment descriptor and go to the Extensions tab

• Directory browsing Enabled:


• Server servlets by classname:


• File Serving


• Precompile JSP

Data source refernece

In J2EE applications both EJBs and Web applications use Data Sources. As per the J2EE specification you should not reference the Data source directly in your application instead you should create a resource reference use it inside your code and then the administrator can map the resource reference to actual data source at the time of deployment

I wanted to try this part so i changed my HelloWorldEJB to access the DB and execute SQL query. This is how my EJB method looks like

 public String sayHello(){
  System.out.println("Inside HelloWorldBean.sayHello()");
  try {
   Context ctx = new InitialContext();
   Object obj  = ctx.lookup("java:comp/env/jdbc/helloWorldDB");
   DataSource ds = (DataSource)obj;
   System.out.println("Data Source " + ds);
   Connection conn = ds.getConnection();
   Statement st = conn.createStatement();
   ResultSet rs = st.executeQuery("SELECT * FROM DBADMIN.CUSTOMER");
   while(rs.next()){
    System.out.println(rs.getString("FIRST_NAME") +" " + rs.getString("LAST_NAME"));
    
   }
  } catch (NamingException e) {
   e.printStackTrace();
  } catch (SQLException e) {
   // TODO Auto-generated catch block
   e.printStackTrace();
  }
  
  return "Hello from HelloWorldEJB";
 }

As you can see the EJB is accessing the Data source from application reference(It starts with java:comp/env)

So i had to define this resource reference, i used RAD define the resource reference by going to References tab in the EJB deployment descriptor editor like this



When i checked the EJB deployment descritpor i could see the resource reference element like this

<resource-ref id="ResourceRef_1252109087246">
 <description id="Description_1252114941484">
 </description>
 <res-ref-name>jdbc/helloWorldDB</res-ref-name>
 <res-type>javax.sql.DataSource</res-type>
 <res-auth>Container</res-auth>
 <res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>

Now if you know the JNDI name of the data source at the time of application assembly then you can map it to the resource reference in RAD like this



Once you bind the resource reference to data source name you will notice that ibm-ejb-jar-bnd.xmi file like this in the META-INF folder of your ejb jar

<?xml version="1.0" encoding="UTF-8"?>
<ejbbnd:EJBJarBinding xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:ejb="ejb.xmi" xmlns:ejbbnd="ejbbnd.xmi" xmi:id="EJBJarBinding_1251662932984">
  <ejbJar href="META-INF/ejb-jar.xml#ejb-jar_ID"/>
  <ejbBindings xmi:id="EnterpriseBeanBinding_1251662932984" jndiName="ejb/ejbs/HelloWorldHome">
    <enterpriseBean xmi:type="ejb:Session" href="META-INF/ejb-jar.xml#HelloWorld"/>
    <resRefBindings xmi:id="ResourceRefBinding_1252109087246" jndiName="jdbc/helloworlddb">
      <bindingResourceRef href="META-INF/ejb-jar.xml#ResourceRef_1252109087246"/>
    </resRefBindings>
    <ejbRefBindings xmi:id="EjbRefBinding_1251663116984" jndiName="ejb/ejbs/HelloWorldHome">
      <bindingEjbRef href="META-INF/ejb-jar.xml#EjbRef_1251663116812"/>
    </ejbRefBindings>
  </ejbBindings>
</ejbbnd:EJBJarBinding>

Now deploy your .ear file in the WAS, it wont prompt you to map resource at the time of deployment but after deployment if you want to change the binding you can go to the application and go to resource reference page to change it like this



In my case i do have resource reference in both EJB and Web module for data source so i can see two mappings there.

If you want you can download sample code from here

EJB Reference

An EJB client can define EJB references, logical names, or nicknames, used by the client to find the EJB homes. When using references, the client can hard code the name of the reference. Then, during deployment, the reference is mapped to the real name in the JNDI namespace to which the EJB is bound. A reference to an EJB specifies either the local or remote home of the EJB.

For remote home interfaces, using EJB references is an option, but also a best
practice. For local home interfaces, however, it is a must, because using an EJB
reference is the only way an EJB client can look up a local home interface.

In my sample HelloWorld EAR application, i do have an HelloWorldEJB which is accessed by HelloWorldServlet. I wanted to try the reference binding so i followed these steps.

First i opened the deployment descriptor of HelloWorldWeb using the Web Application Deployment descriptor editor. In that i went to References tab click on add, and select EJB Reference check box click next. On the next page it displays the HelloWorldEJB project and HelloWorld EJB that is part of the project so i selected it




Now when i looked at the web.xml file i could see a EJB reference element added into it like this

<ejb-ref id="EjbRef_1252108343393">
  <description id="Description_1252113864562">
  </description>
  <ejb-ref-name>ejb/HelloWorld</ejb-ref-name>
  <ejb-ref-type>Session</ejb-ref-type>
  <home>ejbs.HelloWorldHome</home>
  <remote>ejbs.HelloWorld</remote>
  <ejb-link>HelloWorldEJB.jar#HelloWorld</ejb-link>
</ejb-ref>

In addition to this reference the ibm-web-bnd.xmi file was created in the WEB-INF folder of HelloWorldWeb project it looked like this

<?xml version="1.0" encoding="UTF-8"?>
<webappbnd:WebAppBinding xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:webappbnd="webappbnd.xmi" xmi:id="WebAppBinding_1251663066218" virtualHostName="default_host">
  <webapp href="WEB-INF/web.xml#WebApp_ID"/>
  <ejbRefBindings xmi:id="EjbRefBinding_1252108343393" jndiName="ejb/ejbs/HelloWorldHome">
    <bindingEjbRef href="WEB-INF/web.xml#EjbRef_1252108343393"/>
  </ejbRefBindings>
</webappbnd:WebAppBinding>

As you can see the ibm-web-bnd.xmi has a ejbRefBindings element with value of id attribute equal to the value of id attribute of ejb-ref element in web.xml so that means this binding is for the ejb refernece defined in web.xml. If you look at it the value of jndiName is equal to "ejb/ejbs/HelloWorldHome", which is the JNDI name for HelloWorldHome

Now inside my HelloWorldServlet i can call the HelloWorldEJB methods like this

 protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
  System.out.println("Inside HelloWorldServlet.doGet()");
  try {
   Context ctx = new InitialContext();
   Object obj  = ctx.lookup("java:comp/env/ejb/HelloWorld");
   HelloWorldHome helloWorldHome = (HelloWorldHome)obj;
   HelloWorld helloWorld = helloWorldHome.create(); 
   String aString = helloWorld.sayHello();
  } catch (RemoteException ex) {
   ex.printStackTrace();
  } catch (NamingException e) {
   e.printStackTrace();
  } catch (CreateException e) {
   e.printStackTrace();
  } 
  getServletContext().getRequestDispatcher("/index.jsp").include(request , response);
 }

The first part of the context lookup is always java:comp/env followed by name of the ejb reference as defined in the web.xml.

If the EJB that your web application is trying to access is not part of the same EAR then you will have to copy the client jar file in sharedlib and then map the actual JNDI name of the bean to the resource reference at the time of deployment

If you want you can download sample code from here

IBM Extension file

The IBM extension file contains extensions that WAS provides that go beyond what the J2EE specification mandates.Depending on the type of module these files have different elements tha adress different needs. Web Module specific extension file has things like do you want to enable file serving or serving servlet by class name.

These are the extension file names for each of the modules

• EAR File: ibm-application-ext.xmi


• WAR File: ibm-web-ext.xml


• EJB-JAR File : ibm-ejb-jar-ext.xmi

IBM binding file

The IBM binding file is specific to IBM and is packaged in META-INF directory.

The IBM binding file is used to map elements and references into the runtime environment. The IBM binding file, as the name implies binds something abstract about the compliant J2EE descriptor to a concrete runtime component. Elements in a J2EE application such as EJBs, resources such as JDBC data sources, or security roles must be bound to a naming service or underlying concrete resource. Standard J2EE deployment descriptor defines elements or references to other elements. The IBM binding file maps these elements or references to elements actual concrete name under which they are configured.

The binding file can be created at the time of development using Rational Application Developr or WebSPhere Application Server toolkit or It can also be updated, replaced or replaced or generated at the deployment time.

These are the specific binding files for each J2EE module

• EAR : ibm-application-bnd.xmi


• WAR : ibm-web-bnd.xmi


• EJB : ibm-ejb-jar-bnd.xmi


• Application client: ibm-application-client-bnd.xmi

Adding dependency jars using classpath

Every Java archive file contains a file called MANIFEST.MF that is stored in the META-INF directory along with the other descriptors. In case of J2EE modules, MANIFEST.MF is a J2EE compliant way to specify class path information for J2EE module. Each utility JAR, Web Module and EJB module can specify in their MANIFEST the other JARs in the same EAR that are visible to them.

This is sample manifest.mf file for my HelloWorldWeb module. The HelloWorldWeb.war wants to call methods inside the HelloWorldEJBClient.jar which is packaged in same .ear file as that of HelloWorldWeb.war. So in order for HelloWorldWeb.war classes to use methods in the HelloWorldEJBClient.jar it must add it in Class-path,


Manifest-Version: 1.0
Class-Path: HelloWorldEJBClient.jar


If you dont add the .jar file in the Class-path it will result in ClassNotFoundException at runtime.

Note that the MANIFEST can only list JAR files that are stored in the EAR file. Also even though a WAR file is an archive file it cannot be listed on any MANFIEST since the java artifacts within a WAR are only visible to the same WAR.

.ear files deployment descriptor

The deployment descriptor of the EAR file is stored in the META-INF directory in the root of the EAR and is called application.xml. It contains information about the modules that makeup the application.

I have a HelloWorld.ear that contains one HelloWorldEJB module, which is a EJB project and HelloWorldWeb module which is a web module. The HelloWorldWeb module calls methods of HelloWorldEJB

<?xml version="1.0" encoding="UTF-8"?>
<application id="Application_ID" version="1.4" 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">
 <display-name>
 HelloWorld</display-name>
 <module id="EjbModule_1251662896937">
  <ejb>HelloWorldEJB.jar</ejb>
 </module>
 <module id="WebModule_1251663065906">
  <web>
   <web-uri>HelloWorldWeb.war</web-uri>
   <context-root>HelloWorldWeb</context-root>
  </web>
 </module>
</application>

In addition to the standard J2EE deployment descriptors, EAR files produced by the Application Server Toolkit can also include additional WebSphere-specific information used when deploying applications to WebSphere environments. This supplemental information is stored in files called ibm-xxx-xxx-xxx.xmi, also in the META-INF directory.

WebSphere Application Server V6.0 and V6.1 can also store deployment-related information (such as data sources, class loader settings, and so on) as part of an Enhanced EAR file. This information is stored in an ibmconfig subdirectory of the EAR file’s META-INF directory.