Contents

• 1 Introduction
• 2 1. Install Postgresql Driver in Application Server
• 3 2. Define Datasource With @DataSourceDefinition Annotation
• 4 3. Add Datasource to persistence.xml
• 5 Using the Datasource
• 6 Common Glassfish Problems
• 7 Resources

Introduction

Java EE applications use DataSource objects when they access relational databases through the JDBC API. Typically the Datasource that should be used is referenced by its Java Naming and Directory Interface (JNDI) name in the persistence.xml file:

<jta-data-source>java:app/env/myDatasource</jta-data-source>

The Datasource details (host, username, password, database type) for this JNDI name need to be declared somewhere. Prior to Java EE 6, you could create a DataSource object using vendor-specific mechanisms. This could be a deployment descriptor for the application server in the WAR, e.g. glassfish-web.xml or XML configuration files in the application server directory.

In Java EE 6 the @DataSourceDefinition annotation was introduced. With this annotation you can declare ‘application server agnostic’ datasources directly in your code. While this is usually a bad idea for production code, it can be very useful for testing, since you don’t have to change the configuration of the application server. You can just deploy the WAR in any application server and it will run.

In this example we run through the steps for setting up a JPA project with a Postgresql database connection using the @DataSourceDefinition annotation.

1. Install Postgresql Driver in Application Server

First, make sure that the application server is set up to support Postgresql connections. For Glassfish 3 we need to install the Postgresql JDBC drivers.

1. Download the latest JDBC drivers at the Postgresql website.
2. Download the driver file postgresql-.jdbc4.jar and copy it to <glassfish_home>/glassfish/lib/.

For other application servers refer to the documentation.

2. Define Datasource With @DataSourceDefinition Annotation

Next we define the details of the datasource named java:app/env/myDatasource using the @DataSourceDefinition annotation in the Java code. We create a special class for this purpose, in DbConfiguration.java:

import javax.annotation.sql.DataSourceDefinition;
 
@DataSourceDefinition(name = "java:app/env/myDatasource",
		minPoolSize = 0,
		initialPoolSize = 0,
		className = "org.postgresql.ds.PGSimpleDataSource",
		serverName="localhost",
		user = "admin",
		password = "admin",
		databaseName = "test"
)
 
public class DbConfiguration {
}

When the application server deploys the application, all @DataSourceDefinition annotations are processed. The application server will look in all classes, so it doesn’t matter where you put the definition.

Note: you can also define a datasource in the web.xml file that is included in the WAR file.:

   <data-source>
     <name>java:app/env/myDatasource</name>
     <class-name>org.postgresql.ds.PGSimpleDataSource</class-name>
     <server-name>localhost</server-name>
     <port-number>5432</port-number>
     <database-name>test</database-name>
     <user>admin</user>
     <password>admin</password>
   </data-source>

3. Add Datasource to persistence.xml

Our persistence.xml is quite simple, referencing the data source named java:app/env/myDatasource with the JTA transaction type.

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.0" xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
	<persistence-unit name="myUnit" transaction-type="JTA">
		<jta-data-source>java:app/env/myDatasource</jta-data-source>
	</persistence-unit>
</persistence>

Using the Datasource

Now we can make a simple JSF 2.0 web application that uses the database. Let’s make a simple entity with a ‘name’ field.

NamedEntity.java

import java.io.Serializable;
import javax.persistence.Entity;
import javax.persistence.Id;
import javax.persistence.NamedQuery;
import javax.persistence.Table;
 
@Entity
@NamedQuery(name="getAll", query="SELECT c from NamedEntity c")
public class NamedEntity implements Serializable {
	private static final long serialVersionUID = 1L;
 
        @Id
	private String name;
 
	public String getName() {
		return this.name;
	}
 
	public void setName(String name) {
		this.name = name;
	}
}

And we add NamedEntity to our persistence unit:

    <persistence-unit name="myUnit" transaction-type="JTA">
        <jta-data-source>java:app/env/myDatasource</jta-data-source>
        <class>NamedEntity</class>
    </persistence-unit>

We also need a bean that retrieves the names, and makes them available in the JSF page. Since we have declared transaction-type="JTA" in persistence.xml, we can use the @PersistenceContext annotation. This tells the application server to inject a reference to the appropriate EntityManager instance at run-time. In this case it means we will get an EntityManger for the myUnit persistence unit.

TestBean.java

import java.io.Serializable;
import java.util.List;
 
import javax.annotation.sql.DataSourceDefinition;
import javax.faces.bean.ApplicationScoped;
import javax.inject.Named;
import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;
import javax.persistence.TypedQuery;
 
@Named("test")
@ApplicationScoped
public class TestBean implements Serializable
{
	private static final long serialVersionUID = 1L;
 
        // EntityManager is injected here by application server
        @PersistenceContext
        private EntityManager em;
 
	public String getNames()
	{
		TypedQuery<NamedEntity> query = em.createNamedQuery("getAll", NamedEntity.class);
		List<NamedEntity> results = query.getResultList();
 
                StringBuilder result = new StringBuilder("The name are: [");
                String separator = "";
                for (NamedEntity entity: results)
                {
                        result.append(separator).append(entity.getName());
                        separator = ", ";
                }
                result.append("]");
		return result.toString();
	}
}

Then in our JSF page we can reference the TestBean class through an EL expression:

  <h:outputText value="#{test.getNames()}"/>

This code should work without problems, printing all rows from the database, e.g.:

The names are: [Jack, John, Dave]

Common Glassfish Problems

Some errors you may run into when using Glassfish 3 are:

WebappClassLoader unable to load resource

javax.servlet.ServletException: WEB9031: WebappClassLoader unable to load resource 
[org.postgresql.jdbc4.Jdbc4PreparedStatement], because it has not yet been started, or was already stopped

This means the Postgresql JDBC driver cannot be found. Copy the JDBC JAR file to <glassfish_home>/glassfish/lib/ and restart the server.

No PasswordCredential found

WARNING: RAR5038:Unexpected exception while creating resource for pool 
__SYSTEM/pools/__datasource_definition/testApp/java:app/env/myDatasource. 
Exception : javax.resource.spi.SecurityException: No PasswordCredential found
WARNING: RAR5117 : Failed to obtain/create connection from connection pool 
[ __SYSTEM/pools/__datasource_definition/testApp/java:app/env/myDatasource]. 
Reason : com.sun.appserv.connectors.internal.api.PoolingException: No PasswordCredential found
WARNING: RAR5114 : Error allocating connection : 
[Error in allocating a connection. Cause: No PasswordCredential found]

This error indicates the password field for a datasource was left blank. Even though it’s perfectly valid to connect to a database without a password, Glassfish does not like this — it will completely ignore empty properties. Thankfully there is a special meta-string that can be used instead property values to represent a zero length string: ().

ERROR: relation ‘namedentity’ does not exist

Internal Exception: org.postgresql.util.PSQLException: ERROR: relation "namedentity" does not exist
Error Code: 0
Call: INSERT INTO NAMEDENTITY (NAME) VALUES (?)
	bind => [1 parameter bound]
Query: InsertObjectQuery(my.package.namedentity@7f96dfa4)

This means the table associated with an entity does not exist in the database yet. You can tell the JPA implementation to automatically create the tables, but since this is outside the spec there is no fixed syntax. For EclipseLink (the JPA implementation inside Glassfish 3) you have to add two properties to your persistence.xml file:

    <persistence-unit name="myUnit" transaction-type="JTA">
        <!-- other stuf.. -->
	<property name="eclipselink.ddl-generation" value="create-tables" />
	<property name="eclipselink.ddl-generation.output-mode" value="database" />
    </persistence-unit>

Resources

• http://javahowto.blogspot.com/2010/04/datasourcedefinition-examples-in-javaee.html
• https://blogs.oracle.com/enterprisetechtips/entry/datasource_resource_definition_in_java

Contents

• 1 Introduction
• 2 Add JPA Dependencies to pom.xml
• 3 Add JPA Facet to Eclipse Project
• 4 Configure a Persistence Unit

Introduction

the Java Persistence API (JPA) allows for easy managing of relational data in Java applications. It is a replacement of the much criticized EJB 2.0 and EJB 2.1 entity beans. In this post we show how to add JPA support to an existing Maven/Eclipse/JSF2 project with Java EE 6.

With JPA you can do create an entity that is backed by a table in the database. For example you can create a persisted entity (which is just a POJO with some annotations):

Name.java

import javax.persistence.Entity;
import javax.persistence.Table;
import javax.persistence.Id;
import javax.persistence.Column;
 
@Entity
@Table(name="CUSTOMER_INFORMATION")
public class Customer {
    private String name;
 
    @Id
    @Column(name="FULL_NAME")
    public int getName() {
        return name;
    }
 
    public void setName(String name) {
        this.name= name;
    }
}

And a client class that fetches all customer names with and prints them:
Client.java

import javax.persistence.Persistence;
import javax.persistence.EntityManagerFactory;
import javax.persistence.EntityManager;
 
public class Client {
 
    public void printNames() {
        System.out.println("The customer names are:");
        EntityManagerFactory emf = Persistence.createEntityManagerFactory("examplePersistenceUnit");
        EntityManager em = emf.createEntityManager();
 
        final List<Customer> customers = em.createQuery("select c from Customer c")
                .getResultList();
        for (Customer c: customers) {
            System.out.println(c.getName());
        }
    }
}

Example output:

The customer names are:
John
Jack
Dave

Add JPA Dependencies to pom.xml

JPA is part of the Java EE specification, more specifically the javax.persistence.* package. Let’s think about which dependencies we need to add to our pom.xml to make JPA work.

1. Application servers such as Glassfish and JBoss are fully Java EE compliant, and will provide an implementation of the javax.persistence.* classes at runtime. You can just deploy classes that using javax.persistence.Persist to Glassfish, without having to include any JAR files. So no need to modify the pom.xml for that situation.
2. Compiling Java EE code requires that the Java EE API is available on the classpath. We solved this by adding the following dependency:

   <dependency>
       <groupId>javax</groupId>
       <artifactId>javaee-api</artifactId>
       <version>6.0</version>
       <scope>provided</scope>
   </dependency>

   Note that this artifact only provides the Java EE API, not the method bodies. For compilation only this works fine, but you can’t run the code locally with it! I’m not sure why the Java API does not provide implementations, most likely it is to keep the JAR size down and be implementation-independent. But it sure is a headache for many developers.

3. When unit testing the application, e.g. with JUnit, it needs to run locally instead of in an application server such as Glassfish. To run outside of an application server we need provide implementations for the javax.persistence.* classes ourselves. Glassfish uses EclipseLink for its JPA implementation, so let’s change our test-time dependencies to include EclipseLink.

   First, add the EclipseLink repository to the pom:

     <repositories>
       <repository>
           <id>EclipseLink Repo</id>
           <url>http://download.eclipse.org/rt/eclipselink/maven.repo</url>
           <snapshots>
               <enabled>true</enabled>
           </snapshots>
       </repository>
     </repositories>

   Next we include the EclipseLink libraries with the ‘test’ scope above the Java EE API. This way, the javax.persistence classes will be resolved to the EclipseLink artifact instead of the javaee-api artifact. We also need a database driver, in this case PostgreSQL. Together it looks like this:

       <dependency>
         <groupId>org.eclipse.persistence</groupId>
         <artifactId>eclipselink</artifactId>
         <version>2.0.0</version>
         <scope>test</scope>
       </dependency>
       <dependency>
         <groupId>org.eclipse.persistence</groupId>
         <artifactId>javax.persistence</artifactId>
         <version>2.0.0</version>
         <scope>test</scope>
       </dependency>
       <dependency>
         <groupId>javax</groupId>
         <artifactId>javaee-api</artifactId>
         <version>6.0</version>
         <scope>provided</scope>
       </dependency>

Add JPA Facet to Eclipse Project

Eclipse provides excellent JPA support out of the box, but it requires some work to use it with a M2Eclipse/Maven project. Here is how I did it:

1. Re-open the Project Properties go to Project Facets and check ‘JPA’, version 2.0.
2. In the bottom, click on ‘Further configuration available…’.
3. For JPA Implementation choose ‘Disable Library Configuration’, since this is handled by Maven.
4. Set the connection details under ‘Connection’, and click OK. This will create a META-INF directory under src/main/java.
5. Drag the META-INF directory from src/main/java to src/main/resources. Make sure src/main/resources is on the Build Path (rightclick, Build Path, Add to Build Path). You will get an error message and the ‘JPA Content’ node will stop working.
6. Now go into the Project Properties again, and uncheck ‘JPA’, apply the change, and re-enable JPA. Now it should correctly use the persistence.xml file in src/main/resources/META-INF.

Now when building a WAR file, the persistence.xml file will be copied to /WEB-INF/classes/META-INF/persistence.xml, which is one of the valid locations.

Configure a Persistence Unit

Before you can use all the sweet JPA features, you need to create a persistence unit and assign a data source to it (a database connection). Some good sources to learn about the configuration of JPA are:

• Persistence Units and Persistence Contexts
• JPA Concepts – openejb.apache.org
• JPA 2.0 with EclipseLink – Tutorial

You may also be interested in another post here: Using @DataSourceDefinition in Java EE 6 With Postgresql

Contents

• 1 Introduction
• 2 1: Install rtmpdump
• 3 2: Find the RTMPDump Parameters
• 4 3: Record or Play the Stream

Introduction

Ustream.tv doesn’t support opening streams in VLC by default, but it is possible with some effort. Most video streaming sites use the Real Time Messaging Protocol (RTMP) for transmitting video data to your flash player. Using rtmpdump we can connect to RTMP streams, and record them or play them in VLC.

1: Install rtmpdump

On Ubuntu:

$ sudo apt-get install rtmpdump

Binaries for all platforms: here.

2: Find the RTMPDump Parameters

It’s not trivial to find out the correct parameters for rtmpdump, so use this Python script:

#!/usr/bin/env python
# This script finds the rtmpdump command syntax for opening a UStream stream.
 
import sys
import urllib2
import re
 
 
def getVideoData(url):
    # Get the HTML contents
    req = urllib2.Request(url)
    response = urllib2.urlopen(req)
    html = response.read()
 
    # Extract the channel ID from the HTML
    channelId = None
    m = re.search("Channel\sID\:\s+(\d+)", html)
    if (m):
        channelId = m.group(1)
 
    # Extract the channel title from the HTML
    channelTitle = None
    m = re.search("property\=\"og\:url\"\s+content\=\"http\:\/\/www." +
            "ustream\.tv\/(?:channel\/)?([^\"]+)\"", html)
    if (m):
        channelTitle = m.group(1)
 
    amfContent = None
    if (channelId):
        amfUrl = ("http://cdngw.ustream.tv/Viewer/getStream/1/"
        + channelId + ".amf")
        response = urllib2.urlopen(amfUrl)
        amfContent = response.read()
 
        rtmpUrl = re.search("(rtmp\:\/\/[^\x00]+)", amfContent).group(1)
        f = open('tmp.txt', 'w')
        f.write(amfContent)
        streamName = re.search("streamName(?:\W+)([^\x00]+)",
                amfContent).group(1)
 
    return (channelId, channelTitle, rtmpUrl, streamName)
 
 
def getRtmpCommand(rtmpUrl, streamName):
    result = ("rtmpdump -v -r \"" + rtmpUrl + "/" + streamName + "\""
              " -W \"http://www.ustream.tv/flash/viewer.swf\" --live")
    return result
 
 
def main(argv=None):
    # Process arguments
    if argv is None:
        argv = sys.argv[1:]
 
    usage = ("Usage: ustreamRTMPDump.py <ustream channel url> [filename]\n"
            "e.g. \"ustreamRTMPDump.py 'http://www.ustream.tv/ffrc'\"")
 
    if (len(argv) < 1):
        print usage
        return
 
    # Get RTMP information and print it
    url = argv[0]
    print "Opening url: " + url + "\n"
 
    (channelId, channelTitle, rtmpUrl, streamName) = getVideoData(url)
    print "Channel ID: " + channelId
    print "Channel Title: " + channelTitle
    print "RTMP URL: " + rtmpUrl
    print "RTMP Streamname: " + streamName + "\n"
 
    rtmpCmd = getRtmpCommand(rtmpUrl, streamName)
    print "RTMP Command:\n" + rtmpCmd
 
if __name__ == "__main__":
    main()

To use this script to get the rtmpdump command for a UStream channel, simply call it with the channel URL:

python ustreamRTMPDump.py <url>

For example:

$ python ustreamRTMPDump.py "http://www.ustream.tv/decoraheagles"
Opening url: http://www.ustream.tv/decoraheagles
 
Channel ID: 3064708
Channel Title: decoraheagles
RTMP URL: rtmp://ustreamlivefs.fplive.net/ustream3live-live/
RTMP Streamname: stream_live_1_1_3064708
 
RTMP Command:
rtmpdump -v -r "rtmp://ustreamlivefs.fplive.net/ustream3live-live//stream_live_1_1_3064708" -W "http://www.ustream.tv/flash/viewer.swf" --live

Running this command will connect to the stream and write the binary data to the terminal as characters. Not exactly what we want. But we can easily write the stream data to a file, or play it in VLC!

3: Record or Play the Stream

To play the stream in VLC, simply pipe the command into VLC by adding | vlc -.

$ rtmpdump -v -r "rtmp://ustreamlivefs.fplive.net/ustream3live-live//stream_live_1_1_3064708" 
-W "http://www.ustream.tv/flash/viewer.swf" --live | vlc -

To record the stream to a file video.flv simply add -o video.flv to the command.

$ rtmpdump -v -r "rtmp://ustreamlivefs.fplive.net/ustream3live-live//stream_live_1_1_3064708" 
-W "http://www.ustream.tv/flash/viewer.swf" --live -o video.flv

You can then play this file in VLC, even while it is being recorded:

$ vlc video.flv

Example Output

$ rtmpdump -v -r "rtmp://ustreamlivefs.fplive.net/ustream3live-live//stream_live_1_1_3064708" -W "http://www.ustream.tv/flash/viewer.swf" --live | vlc -
RTMPDump v2.4
(c) 2010 Andrej Stepanchuk, Howard Chu, The Flvstreamer Team; license: GPL
VLC media player 2.0.1 Twoflower (revision 2.0.1-0-gf432547)
WARNING: You haven't specified an output file (-o filename), using stdout
[0x8d07908] main libvlc: Running vlc with the default interface. Use 'cvlc' to use vlc without interface.
ERROR: RTMP_HashSWF: couldn't contact swfurl http://www.ustream.tv/flash/viewer.swf (HTTP error 302)
Connecting ...
INFO: Connected...
Starting Live Stream
INFO: Metadata:
INFO:   author                
INFO:   copyright             
INFO:   description           
INFO:   keywords              
INFO:   rating                
INFO:   title                 
INFO:   presetname            Custom
INFO:   creationdate          Sat May 19 23:01:07 2012
INFO:   videodevice           ATI AVStream Analog Capture
INFO:   framerate             30.00
INFO:   width                 720.00
INFO:   height                480.00
INFO:   videocodecid          avc1
INFO:   videodatarate         500.00
INFO:   avclevel              50.00
INFO:   avcprofile            77.00
INFO:   videokeyframe_frequency1.00
INFO:   audiodevice           Microphone (Realtek High Defini
INFO:   audiosamplerate       22050.00
INFO:   audiochannels         1.00
INFO:   audioinputvolume      100.00
INFO:   audiocodecid          .mp3
INFO:   audiodatarate         48.00
0.634 kB / 0.00 sec"sni-qt/24365" WARN  20:30:09.944 void StatusNotifierItemFactory::connectToSnw() Invalid interface to SNW_SERVICE 
36.430 kB / 0.00 sec[flv @ 0xb5211aa0] Estimating duration from bitrate, this may be inaccurate
214.671 kB / 1.13 sec

Contents

• 1 Introduction
• 2 What Are We Building?
• 3 Project Setup with Maven Archetypes
• 4 Adding Dependencies To POM
• 5 Configuring the Deployment Descriptor
• 6 Adding a Bean
• 7 Adding a JSF Page
• 8 Deploying Manually In Glassfish 3
• 9 Importing Into Eclipse
  • 9.1 Set Java version in POM to 1.6
  • 9.2 Install Eclipse Plugins
  • 9.3 Import the Project
  • 9.4 Installing Glassfish Support
  • 9.5 Deploying to Glassfish
  • 9.6 Add Project to SVN

Introduction

Serious Java Web application development requires a lot of different applications. In addition to a JDK, an IDE and an application server you may need a Web application framework, a build system and some form of version control. Unsurprisingly, getting set up for development can be quite the task.

In this post we’ll take a look at setting up a Web application project from start to finish. The software we will use is:

What Are We Building?

Different applications come in different forms.

• A Windows application written in C++ may be compiled to a .exe file.
• Runnable Java GUI applications often come in a JAR (Java ARchive).
• Java Web applications are packaged in WAR and EAR files.

We are building a Web application, so the product of building our project will be a WAR file. The Glassfish application server extracts a WAR file and runs the application inside it. The WAR file also contains a deployment descriptor, web.xml that describes how the application server should run the WAR.

The structure of a WAR file looks like this (source):

Project Setup with Maven Archetypes

Now that we know what we are building, it is time to start setting up the project. The directory/file structure of the project we are creating is very different from the structure of the WAR file. Our build tool, Maven, makes the ‘translation’ between the project structure and the WAR structure. It takes care of compiling and packaging up the files in the project into a valid WAR file that is ready for deployment.

We don’t have to start completely from scratch with the project. Maven can download pre-made, barebones projects called archetypes. Archetypes are nothing more than a bunch of files and folders that are packaged up and given a name.

There are currently 588 archetypes, 21 of which contain “jsf” in their name. Most of these archetypes are quite heavyweight: they come with pretty big pom.xml files. Instead of using these, we will start off with a very basic non-jsf archetype, and add only the things we really need.

First we will download the archetype maven-archetype-webapp with the mvn archetype:generate command. Be be sure to choose a fitting groupId and artifactId:

>mvn archetype:generate -DarchetypeArtifactId=maven-archetype-webapp
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:2.2:generate (default-cli) @ standalone-pom >>>
...
[INFO] Generating project in Interactive mode
Define value for property 'groupId': : mygroup.com
Define value for property 'artifactId': : myprojectname
Define value for property 'version':  1.0-SNAPSHOT: :
Define value for property 'package':  mygroup.com: :
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

This creates a very simple Mavenized Web application project in a directory named myprojectname. The contents of this folder are:

The default pom.xml file is very simple, containing only one dependency. The packaging type is set to war, which is what we need.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>mygroup.com</groupId>
  <artifactId>myprojectname</artifactId>
  <packaging>war</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>myprojectname Maven Webapp</name>
  <url>http://maven.apache.org</url>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <build>
    <finalName>myprojectname</finalName>
  </build>
</project>

Adding Dependencies To POM

Our project will use JSF 2.0 web framework, and run on the Glassfish application server. JSF is part of the standard Java EE platform, which means it’s built-in to any compliant Java EE application server, such as Oracle’s WebLogic, GlassFish Open Source Edition, or JBoss AS. But it can also be used as a standalone library in servlet containers such as Tomcat and Jetty.

In order to be able use JSF (the javax.faces package) in our source code we must add a dependency for it in the pom.xml. Add this dependency for the entire Java EE 6 API (including JSF and CDI):

<dependency>
    <groupId>javax</groupId>
    <artifactId>javaee-api</artifactId>
    <version>6.0</version>
    <scope>provided</scope>
</dependency>

The provided scope means that Maven assumes the dependency is provided by the application server at run-time. Maven will only add the JAR to the classpath for compilation and testing phases, but it will not be included in the WAR file. This is what we want, because Glassfish 3 contains a full Java EE implementation including JSF 2.0.

Configuring the Deployment Descriptor

A deployment descriptor describes how a Web application should be deployed. In the past, using a web.xml file in the WEB-INF directory was required. However, with the new features in the Servlet 3.0 specification in Java EE 6 it has become possible to use annotations instead of XML configuration files such as web.xml. It doesn’t mean the web.xml is now obsolete, but its size can be reduced. Information specified in the deployment descriptor takes precedence over the information specified through Annotations.

Part of the deployment descriptor are servlet mappings that describe which URLs are passed to the Faces Servlet. Some application servers (including GlassFish) automatically provide a servlet mapping for the /faces/*, *.faces, and *.jsf patterns. The *.jsf pattern means that a request to http://localhost/myprojectname/index.jsf is passed to the Faces Servlet. By default, the Faces Servlet then looks for a file but with a .jsp

Discard the outdated web.xml that came with the archetype, and replace it with this web.xml:

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
      version="3.0">
<servlet>
    <servlet-name>Faces Servlet</servlet-name>
    <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
</servlet>
<servlet-mapping>
    <servlet-name>Faces Servlet</servlet-name>
    <url-pattern>*.xhtml</url-pattern>
</servlet-mapping>
<context-param>
    <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
    <param-value>.xhtml</param-value>
</context-param>
</web-app>

This instructs the application server to pass .xhtml requests to the Faces Servlet, and to let the Faces Servlet look for .xhtml files on the filesystem.

Adding a Bean

A bean is a Java class that is managed by the JSF framework, and can be referenced from JSF pages using the bean name. It is a historical accident that there are two separate mechanisms, CDI beans and JSF managed beans, for beans that can be used in JSF pages. The consensus for Java EE 6 seems to be CDI beans, so we will use that method.

In previous JSF versions, each bean had to be declared in a faces-config.xml file. Thankfully we now have annotations, which makes this file obsolete in most cases. Create a new source file at /src/main/java/com/mygroup/Hello.java.

package com.mygroup;
 
import javax.inject.Named;
 
@Named
public class HelloBean
{
    public String getGreeting() 
    {
        return "Hello World!";
    }
}

The @Named annotation means the class is a CDI bean. One thing we need to do now is tell the server that this project is a module containing CDI beans. To do this, we add an empty file called beans.xml to the project at /src/main/webapp/WEB-INF/beans.xml.

Adding a JSF Page

We have defined in the web.xml file that our views use the .xhtml extension. So we remove the /src/main/webapp/index.jsp file that came with the archetype, and create a new file /src/main/webapp/index.xhtml.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:ui="http://java.sun.com/jsf/facelets"
      xmlns:f="http://java.sun.com/jsf/core"
      xmlns:h="http://java.sun.com/jsf/html">
 
<h:head>
  <title>My JSF Page</title>
</h:head>
<h:body>
    <h1>Bean Test</h1>
    <h:outputText value="HelloBean says: #{helloBean.greeting}" />
</h:body>
</html>

• Since this is a JSF page, we can use h:, f: and ui: tags. These tags will be processed by the Faces Servlet.
• The EL statement #{helloBean.greeting} is evaluated when the page is requested. This should call the getGreeting() method of the HelloBean class.

The completed project should look like this:

Deploying Manually In Glassfish 3

OK, now we should have a working JSF/Maven project. Let's try to deploy and run it manually before we import it into Eclipse.

Package the project into a WAR file with the mvn package command:

>mvn package
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

This builds the project into a WAR file at /target/myprojectname.war.

Next, we start up a Glassfish 3 server with the asadmin start-domain command.

asadmin start-domain --verbose domain1

Now copy the WAR file to the autodeploy directory of your domain directory, e.g. glassfish/domains/domain1/autodeploy. You will see some output from the asadmin process, which can help identify any problems with the project. Let's assume that things didn't blow up in your face and the deployment was succesful, and you see something like this:

[#|2012-05-12T23:40:30.620+0200|INFO|glassfish3.1.2
|[AutoDeploy] Successfully autodeployed : C:\glassfish3\glassfish\domains\domain1\autodeploy\myprojectname.war.|#]

Now open a browser and open the page, e.g. at http://localhost:8080/myprojectname/index.xhtml. You should see "HelloBean says: Hello World".

Importing Into Eclipse

Now that we have a working JSF/Maven project, it is time to import the project into Eclipse.

Set Java version in POM to 1.6

It is a good idea to tie the project to a specific JDK version, to ensure the build stays the same when a newer JDK version is used. We do this by adding some parameters for the maven-compiler-plugin to our pom. Since we are developing for Java EE 6, we will specify version 1.6. Change the <build> section to this:

  <build>
    <plugins>
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>1.6</source>
          <target>1.6</target>
        </configuration>
      </plugin>
    </plugins>
    <finalName>myprojectname</finalName>
  </build>

Install Eclipse Plugins

For JSF development you need the Java EE version of Eclipse, for this guide Eclipse Indigo SR2 was used. After installing Eclipse we need to add three plugins through Help -> Eclipse Marketplace.

• Subclipse: This plugin provides SVN integration.
• Maven Integration for Eclipse (a.k.a. m2eclipse): This plugin adds basic Maven support to Eclipse. Obviously.
• Maven Integration for Eclipse WTP (a.k.a. m2e-wtp): This plugin integrates m2eclipse with the Web Tools Project, which handles Web application specific stuff in Eclipse.

Import the Project

Go to File -> Import, and choose Existing Maven Projects. Browse to the directory where the pom.xml is located, and click Finish. The project should now be imported, and initialized.

If we look at the Project Facets (under Project -> Properties) we see that the Java version has been correctly set to 1.6, and the Dynamic Web Module is set to support Servlet 3.0.

Installing Glassfish Support

Eclipse does not come with pre-installed Glassfish server support, but fortunately this can be added with a few clicks.

1. Open the Servers view through Window -> Show View -> Others.
2. Right-click in the Servers view and select New -> Server.
3. Click "Download additional server adapters" in the top-right and install the "Oracle Glassfish Server Tools" module.

Deploying to Glassfish

Create a new Glassfish server instance through the Servers view. We choose the latest available Glassfish edition, in my case it was Glassfish 3.1.2. Then we are prompted for the installation directory of the server. We can either select the path of an existing Glassfish installation, or choose an empty directory and click "Install Server" to make Eclipse download a fresh installation for us.

Now we can add a project to the Glassfish server by right-clicking it and choosing Add and Remove...:

Start the server, and your project will be served by Glassfish!

Add Project to SVN

As a final step we can upload the project to an SVN repository, so we can work on it with others and keep a history of the code. A detailed description of the process can be found in another post on this blog. Be sure to the add target directory to svn:ignore by rightclicking it and selecting Team -> Add to svn ignore...

In order for other developers to immediately have a working project, we will need to upload all other project files, including .project, .classpath and the .settings directory. Of course the other developers will also need to have the same plugins installed.

Contents

• 1 Introduction
• 2 Example Project
• 3 Maven Configuration Is Mostly Implicit
• 4 Executed Lifecycle Phases
  • 4.1 1. resources:resources
  • 4.2 2. compiler:compile
  • 4.3 3. resources:testResources
  • 4.4 4. compiler:testCompile
  • 4.5 5. surefire:test
  • 4.6 7. war:war
• 5 Dependencies

Introduction

When dealing with a Java Web applications, the completed application is commonly delivered as a WAR file. The Maven build system can easily be set up to create WAR files. In this post we take an in-depth look at how Maven goes from a source project to the final WAR product.

Used software: Apache Maven 3.0.4.

The structure of a WAR file looks like this (source):

Example Project

Let’s look at a very simple Mavenized Web application project in a directory named myprojectname. The contents of this folder are:

The pom.xml file looks like this:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>mygroup.com</groupId>
  <artifactId>myprojectname</artifactId>
  <packaging>war</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>myprojectname Maven Webapp</name>
  <url>http://maven.apache.org</url>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <build>
    <finalName>myprojectname</finalName>
  </build>
</project>

To package this bare-bones project into a WAR file we use the mvn package command.

C:\Projects\myprojectname>mvn package
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building myprojectname Maven Webapp 1.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO]
...
[INFO] --- maven-war-plugin:2.1.1:war (default-war) @ myprojectname ---
[INFO] Packaging webapp
[INFO] Assembling webapp [myprojectname] in [C:\Projects\myprojectname\target\myprojectname]
[INFO] Processing war project
[INFO] Copying webapp resources [C:\Projects\myprojectname\src\main\webapp]
[INFO] Webapp assembled in [18 msecs]
[INFO] Building war: C:\Projects\target\myprojectname.war
...

This creates a WAR file at /target/myprojectname.war. The execution of this mvn package command is the scenario we will take a closer look at. An overview of the operation is displayed in the image below.

Maven is used to build a WAR file from the source project, through the "mvn package" command.

Maven Configuration Is Mostly Implicit

We know that Maven can succesfully create a WAR file from the source project. But our pom.xml file is almost empty, so how does Maven know things like where the .java files for compilation are, or what the exact structure of the WAR file should be? The answer is that these settings are implicit. Maven uses a “convention over configuration” approach, and provides default values for the project’s configuration.

First, some things are implicit because of the default way Maven plugins are bound to the lifecycle phases. For example, the compile phase has the goal compiler:compile assigned to it by default. This means that when executing the compile phase, the compile goal of the compiler plugin is called. When you select WAR packaging in your pom.xml, the war:war goal (which creates the WAR) is bound to the package phase.

Second, plugins define default values for their parameters that are used when no explicit value is passed. For example, the compiler:compile goal has a parameter called compilerId. This parameter has the value javac by default, meaning the regular JDK compiler will be used. A project’s pom.xml file can override this default to use a different compiler.

Finally, some settings are contained in the Super POM that every pom.xml implicitly inherits. For Maven 3 the Super POM is located in maven_dir/lib/maven-model-builder-3.0.3.jar:org/apache/maven/model/pom-4.0.0.xml. In this file we find the default directory locations for source files, resources, test source files, etc:

  <build>
    <directory>${project.basedir}/target</directory>
    <outputDirectory>${project.build.directory}/classes</outputDirectory>
    <finalName>${project.artifactId}-${project.version}</finalName>
    <testOutputDirectory>${project.build.directory}/test-classes</testOutputDirectory>
    <sourceDirectory>${project.basedir}/src/main/java</sourceDirectory>
    <scriptSourceDirectory>src/main/scripts</scriptSourceDirectory>
    <testSourceDirectory>${project.basedir}/src/test/java</testSourceDirectory>
    <resources>
      <resource>
        <directory>${project.basedir}/src/main/resources</directory>
      </resource>
    </resources>
    <testResources>
      <testResource>
        <directory>${project.basedir}/src/test/resources</directory>
      </testResource>
    </testResources>
  ...
  </build>

These mappings define Maven’s Standard Directory Layout, and it is encouraged to keep this default structure in all your Maven projects.

Executed Lifecycle Phases

If you are having trouble understanding this section, go read about Maven lifecycles, phases, goals and plugins here.

For our project, when mvn package is entered this will execute all lifecycle phases that have a goal bound to them in sequence, up to and including the package phase. In our case this means six phases are executed: process-resources, compile, process-test-resources, test-compile, test and package.

Each phase consists of one or more goals. Goals are provided by Maven plugins: a plugin may have one or more goals wherein each goal represents a capability of that plugin. For example, the Compiler plugin has two goals: compiler:compile and compiler:testCompile.

We can use the mvn help:describe -Dcmd=phasename command to list the lifecycle phases along with bound goals for a project. Example:

C:\Project\myprojectname>mvn help:describe -Dcmd=package
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building myprojectname Maven Webapp 1.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] --- maven-help-plugin:2.1.1:describe (default-cli) @ myprojectname ---
[INFO] 'package' is a phase corresponding to this plugin:
org.apache.maven.plugins:maven-war-plugin:2.1.1:war
 
It is a part of the lifecycle for the POM packaging 'war'. This lifecycle includes the following phases:
* validate: Not defined
* initialize: Not defined
* generate-sources: Not defined
* process-sources: Not defined
* generate-resources: Not defined
* process-resources: org.apache.maven.plugins:maven-resources-plugin:2.5:resources
* compile: org.apache.maven.plugins:maven-compiler-plugin:2.3.2:compile
* process-classes: Not defined
* generate-test-sources: Not defined
* process-test-sources: Not defined
* generate-test-resources: Not defined
* process-test-resources: org.apache.maven.plugins:maven-resources-plugin:2.5:testResources
* test-compile: org.apache.maven.plugins:maven-compiler-plugin:2.3.2:testCompile
* process-test-classes: Not defined
* test: org.apache.maven.plugins:maven-surefire-plugin:2.10:test
* prepare-package: Not defined
* package: org.apache.maven.plugins:maven-war-plugin:2.1.1:war
* pre-integration-test: Not defined
* integration-test: Not defined
* post-integration-test: Not defined
* verify: Not defined
* install: org.apache.maven.plugins:maven-install-plugin:2.3.1:install
* deploy: org.apache.maven.plugins:maven-deploy-plugin:2.7:deploy
 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2.496s
[INFO] Finished at: Sat May 12 04:30:35 CEST 2012
[INFO] Final Memory: 5M/121M
[INFO] ------------------------------------------------------------------------

Next, we look at each goal that is goals executed in the WAR build in more detail.

1. resources:resources

The resources:resources goal copies resources for the main source code to the main output directory.

2. compiler:compile

The compiler:compile goal compiles the application source files.

3. resources:testResources

The resources:testResources goal copies resources for the unit test source code to the test output directory.

4. compiler:testCompile

The compiler:compile goal compiles the application unit test sources.

5. surefire:test

The surefire:test goal executes the unit tests of an application, on the classes in the /target/test-classes directory. The build stops if a unit test fails. When there are no test classes, the goal is always succesful.

7. war:war

The war:war goal builds a WAR file. It gathers all needed files in the /target/myprojectname/ directory, then packages them up into myprojectname.war. One of these steps is copying the contents of /src/main/webapp/ to /target/myprojectname/.

Other important tasks performed by the war plugin are copying the compiled classes are copied to WEB-INF/classes/, and runtime dependencies to WEB-INF/lib/. By default the WAR builder also includes two Maven descriptor files (details):

• The pom file, located in the archive in META-INF/maven/${groupId}/${artifactId}/pom.xml
• A pom.properties file, located in the archive in META-INF/maven/${groupId}/${artifactId}/pom.properties. During the build this file is generated in the /target/maven-archiver/pom.properties directory.
  The file looks something like this:

  #Generated by Maven
  #Sat May 12 00:50:42 CEST 2012
  version=1.0-SNAPSHOT
  groupId=mygroup.com
  artifactId=myprojectname

Finally, the /target/myprojectname directory is packaged up into a WAR file. In addition the pom file and the pom.properties file are put in the META-INF/maven directory of the archive, and a manifest file is generated at META-INF/MANIFEST.MF.

The final step is packaging everything into a WAR file. The bulk of the files comes from the target/myprojectname directory (red), and some additional files are included (green).

The final WAR is placed in /target/myprojectname.war. This WAR can now be deployed with a servlet container (e.g., Tomcat) or application server (e.g., Glassfish).

Dependencies

Currently, our pom.xml only has one dependency (JUnit). Let’s add another dependency and see what happens when the WAR is built.

We add this dependency to the pom:

<dependency>
    <groupId>log4j</groupId>
    <artifactId>log4j</artifactId>
    <version>1.2.16</version>
</dependency>

When no scope is specified, a dependency has the compile scope (read more). The compile scope means that the dependency is available during compilation, testing, and at runtime.

Every dependency that is needed at runtime must be distributed with the application. So when we run mvn package with this pom, Maven downloads the log4j JAR and includes it the /WEB-INF/lib directory in the WAR file.

Contents

• 1 Introduction
• 2 Building Blocks
  • 2.1 Servlets
  • 2.2 JSP
  • 2.3 Web Frameworks
• 3 Which Technology Should I Use?
• 4 What is Java EE?
  • 4.1 Language vs Platform
  • 4.2 Java SE vs Java EE
• 5 Java Web Application Servers
  • 5.1 Web Server
  • 5.2 Web Container
  • 5.3 Application Server
• 6 How Is a Java Web Application Distributed?
  • 6.1 JAR: Java ARchive
  • 6.2 WAR: Web application ARchive
  • 6.3 EAR: Enterprise ARchive
• 7 Sources

Introduction

A Web application is an application that is accessed over a network such as the Internet or an intranet. While the earliest websites served only static web pages, dynamic response generation quickly became possible via CGI scripts, JSPs (JavaServer Pages), servlets, ASPs (Active Server Pages), server-side JavaScripts, PHP, or some other server-side technology.

Java has become a popular language for creating dynamic Web applications over the last 15 years, due to the introduction of servlets, JSP, and frameworks such as JSF and Spring. In this post we give an overview of these technologies, and explain the the major differences between them.

Building Blocks

For the sake of simplicity we distinguish three types of Web application building blocks: servlets, JSPs and frameworks

Servlets

In Java, Web applications consist of servlets. A servlet is a small Java program that runs within a Web server. Servlets receive and respond to requests from Web clients, usually across HTTP. An example of a servlet that takes a request and returns a page with the numbers 1 to 10 is given below.

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
 
public class HelloWorldServlet extends HttpServlet
{
  public void doGet (HttpServletRequest req,
                     HttpServletResponse res)
    throws ServletException, IOException
  {
    PrintWriter out = res.getWriter();
    out.println("<html>");
    out.println("<head><title>Greeting Page</title></head>");
    out.println("<body>The numbers are:<ul>");
    for (int i=1; i<=10; i++) 
    {
      out.println("<li>" + i + "</li>");
    }
    out.println("</ul></body>");
    out.println("</html>");
    out.close();
  }
}

JSP

Developing a Web application in plain servlets was a pain: imagine the horror of having hundreds of println() calls with HTML tags or Javascript code spread out over all your classes. This problem was alleviated in 1999 with the release of JavaServer Pages (JSP). With JSP you could write HTML in a JSP file, and the server would automatically create a servlet from the page. JSP also allows you to write blocks of Java code inside the JSP.

An example of a simple JSP page that prints a bullet list with the numbers 1 to 10 is given below.

<html>
<body>
The numbers are:
<ul>
<%
    for (int i=1; i<=10; i++) {
        %>
        <li><%= i %></li>
        <%
    }
%>
</ul>
</body>
</html>

Unfortunately, having Java inside HTML proved almost as awkward as having HTML inside Java. It could easily create a hard to read mess. It was only years later when the introduction of JSTL and EL alleviated this problem somewhat by providing tags and expressions that could be used in JSP’s, instead of Java code.

Web Frameworks

Even with the improvements to JSP, developing with “plain vanilla” JSP/servlets can be quite laborious: you’ll have to bring in a lot of code to control, preprocess, postprocess, gather data, validate, convert, listen, etc the HTTP request and response. The shortcomings of plain servlets and JSP sparked the creation of many Web frameworks that intended to make Web application development easier. These frameworks are built on top of JSP/servlet technology: most frameworks use JSP in some shape or form, and all frameworks eventually create servlets.

A key selling point of most frameworks is the separation between the presentation of a page and the underlying logic. This means there is no intermingling of HTML and Java! In addition, many frameworks provide libraries for database access, templating frameworks and session management, and they often promote code reuse. A timeline with the release dates of some well-known Web frameworks is displayed below ¹.

A timeline with the release dates of some Web frameworks. Most of them are Java frameworks, but some other ones are included.

Over the last 10 years plain servlets and JSP have gradually been replaced by Web frameworks as the technology of choice. In 2012, using frameworks has become the standard; using JSP is only an option for very small Web applications. For larger projects frameworks are a must, since they remove the need to reinvent the wheel over and over during implementation.

The interesting parts of a Hello World application for the JSF 2.0 framework look something like this:

Hello.java

package hello;
 
import javax.faces.bean.ManagedBean;
 
@ManagedBean
public class Hello {
 
    final String world = "Hello World!";
 
    public String getworld() {
        return world;
    }
}

hello.jsf

<html lang="en"
      xmlns="http://www.w3.org/1999/xhtml"
      xmlns:h="http://java.sun.com/jsf/html">
    <h:head>
        <title>Facelets Hello World</title>
    </h:head>
    <h:body>
        #{hello.world}
    </h:body>
</html>

Which Technology Should I Use?

That’s a good question. As with all things software, there is no unified answer (another ten posts could be dedicated to trying to give a complete answer). Servlets and JSPs are lightweight, but there are other lightweight technologies to consider, e.g. PHP. Frameworks are more powerful, but if you are building a very small Web application using a full-blown framework may be overkill. It all depends on your demands and personal preference.

If you are considering a framework, you have to choose between an uncountable number of web-frameworks that exists in the Java environment. The bottom line is that most frameworks will do the job, and you can’t really judge a framework until you have actually tried it. Here are some links to get you started.

• Comparing JVM Web Frameworks (2012)
• Categorization of Web Frameworks in the Java Environment (2012)
• Java Productivity Report (2011)

An overview of which Java EE standards are used the most (source: ZeroTurnaround).

What is Java EE?

In many documents about Java Web applications you will run into the term Java EE, but what does it mean exactly?

The short answer is that Java EE refers to Java Platform Enterprise Edition. The long answer is, well, longer.

Language vs Platform

Java technology is both a programming language and a platform. The Java programming language is a high-level object-oriented language that has a particular syntax and style. A Java platform is a particular environment in which Java programming language applications run. Every platform has an API that defines things like the classes that are available to the programmer, and which functions are available in each class.

When most people think of the Java programming language, they think of the Java SE API. Java SE’s API provides the core functionality of the Java programming language. It defines everything from the basic types and objects of the Java programming language to high-level classes that are used for networking, security, database access, graphical user interface (GUI) development, and XML parsing.

So, the Java language defines that you can use an if statement, and that single line comments start with //:

if (x == y)
{
  // A comment
}

And the Java SE API defines the existence of the List, ArrayList and String objects:

List<String> = new ArrayList<String>();

The platform APIs are just APIsimplementation of classes defined in the API. There are various different implementations by other parties, e.g. the open source Java SE implementation OpenJDK.

Java SE vs Java EE

The editions of the Java platform range from lightweight to heavyweight. For ‘normal’ computers two versions are available: Java SE and Java EE. The image below gives an overview (source).

An overview of Java Platform editions. The Java EE edition is the 'largest' of all java versions.

Java Platform Enterprise Edition or Java EE is the enterprise Java computing platform. The platform was known as Java 2 Platform, Enterprise Edition or J2EE until the name was changed to Java EE in version 5. The current version is called Java EE 6. Java EE extends Java SE, providing an API for fault-tolerance, object-relational mapping, distributed and multi-tier architectures, and web services.

Some of the top-level packages (there are 11 in total) defined by the Java EE API are:

javax.faces.*          This package defines the root of the JavaServer Faces (JSF) API.
javax.servlet.*        The servlet specification defines a set of APIs to service mainly HTTP requests. It includes the JavaServer Pages specification.
javax.ejb.*            The Enterprise JavaBean (EJB) specification defines a set of lightweight APIs that an object container (the EJB container) will support in order to provide transactions (using JTA), remote procedure calls (using RMI or RMI-IIOP), concurrency control, dependency injection and access control for business objects.
javax.persistence.*    This package contains the classes and interfaces that define the contracts between a persistence provider and the managed classes and the clients of the Java Persistence API (JPA).

The reference implementation of the Java EE platform is called Glassfish. This implements the new packages defined by Java EE. There are several other implementations that provide a runtime environment for Java EE programs, such as JBoss and WebSphere. Since Java EE runs ‘on top’ of Java SE, Java EE programs can use all features of Java SE.

Note that just because Java EE stands for Enterprise Edition, it does not mean that it is used only by enterprises. Java EE is the name given to a set of specifications that are bundled together to form a platform. The moment you need to write a web application, you need to use the Servlet + JSP specifications at a bare minimum, which are both contained in the EE specification. So you can simply do more stuff with a Java EE application because it can use the additional APIs provided by the Java EE specification.

Java Web Application Servers

Understanding the differences between a web server, a servlet container and an application server is important when learning how a Java Web application is presented to its end users. The servlet/application/EJB container terms are a bit ambiguous, but we will try to come to a workable definition. Let’s take a look.

Web Server

A Web server handles the HTTP protocol. When the Web server receives an HTTP request, it responds with an HTTP response, such as sending back an HTML page. To process a request, a Web server may respond with a static HTML page or image, send a redirect, or delegate the dynamic response generation to some other program such as CGI scripts, JSPs (JavaServer Pages), servlets, ASPs (Active Server Pages), server-side JavaScripts, or some other server-side technology. Whatever their purpose, such server-side programs generate a response, most often in HTML, for viewing in a Web browser ². The Web server itself does not dynamically generate responses, it just handles receiving the request and sending the response.

The most commonly used Web servers are Apache, Microsoft IIS and nginx.

Web Container

A Web container (or servlet container) is a program that provides an environment for the servlets and JSP to run. Putting it differently we can say that a Web container is combination of a Servlet Engine and a JSP Engine. Most Web containers also include a Web server, so they can run stand-alone.

The Web container is responsible for managing the lifecycle of servlets, mapping a URL to a particular servlet and ensuring that the URL requester has the correct access rights. If an HTTP Request refers to a Web Component (typically a servlet or a JSP) then the request is forwarded to the Web Container and the result of the request is sent back to Web Server, which uses that result to prepare the HTTP Response for the particular HTTP Request.

So a Web container provides a runtime environment for a subset of the Java EE specification, usually only the JSP and Servlet parts. This means a programmer could write the following:

import javax.servlet.*;
import javax.servlet.http.*;

This would work just fine, because the Web container contains an implementation of javax.servlet.*. The use of JSP is also allowed, e.g. using <jsp> tags.

<jsp:include page="hello.jsp"/>

But you can’t use other Java EE features such as Enterprise Java Beans (EJBs):

import java.util.Collection;
import javax.ejb.Remote;
 
@Remote
public interface Cart {
    public void addItem(String item);
    public void removeItem(String item);
    public Collection getItems();
}

This will not work because the Web container does not know the javax.ejb.* package. When you do need EJBs it may be possible to extend a Web container with additional Java EE implementation parts, but it is a much better idea to use a full-fledged Java EE application server.

The most common Web container are Tomcat and Jetty. Tomcat 7 implements two specifications: JSP 2.2 and Servlet 3.0.

Application Server

An application server (a.ka. Java EE server or application container) is a server that provides support for the entire Java EE specification. It can run applications that use EJBs, provides transaction support through the javax.transaction.* package, etc. In addition it provides the capabilities of a Web Container as well as of a Web Server. The image below shows a full application server (source).

An application server provides support for the full Java EE specification.

In an application server, programs can happily use the full Java EE specification, e.g. declaring Entity Beans:

import javax.persistence.Entity;
import javax.persistence.GeneratedValue; 
import javax.persistence.Id;
import javax.persistence.Table;
 
@Entity  
@Table(name="bookbank")
public class Book implements Serializable 
{   
  @Id 
  Long empid;
 
  @GeneratedValue 
  public Long getId() 
   { return id; }  
    public void setId(Long id)  
  { this.id = id; }  
}

How Is a Java Web Application Distributed?

As we just learned Java Web applications are run in Web containers or application servers. But how do you present a Web application to the server? The short answer is this:

Web applications are packaged in WAR and EAR files. Web containers (e.g. Tomcat) accept WAR files. Application servers (e.g. Glassfish) accept WAR files and EAR files.

For a more detailed explanation we have to dig deeper…

A Java EE application is delivered in a Java Archive (JAR) file, a Web Archive (WAR) file, or an Enterprise Archive (EAR) file. A WAR or EAR file is a standard JAR file with a .war or .ear extension. Using JAR, WAR, and EAR files and modules makes it possible to assemble a number of different Java EE applications using some of the same components⁴. Note that a Java Web application is always a Java EE application, but the opposite is not true. Only Java EE applications packages in WAR and EAR files are web applications.

JAR: Java ARchive

A JAR (Java ARchive) is an archive file format typically used to aggregate many Java class files and associated metadata and resources (text, images and so on) into one file to distribute application software or libraries on the Java platform.

• Based on the ZIP format: it can aggregate many files and directories into one aggregate file, possibly compressing them.
• A manifest file is a specific file contained within a JAR archive. It is used to define information about the JAR.
• The manifest file is named MANIFEST.MF and must be located at META-INF/MANIFEST.MF in the JAR.
• One of the most common uses of JAR files is to bundle all the .class files, and other required component files of a library into a JAR file and include that JAR file into the CLASSPATH of another Java application which requires the services of that library.
• EJB modules contain class files for enterprise beans and an EJB deployment descriptor. EJB modules are packaged as JAR files with a .jar extension.
• Application client modules, which contain class files and an application client deployment descriptor. Application client modules are packaged as JAR files with a .jar extension.

WAR: Web application ARchive

A WAR file (or Web application ARchive) is a JAR file used to distribute a collection of JavaServer Pages, Java Servlets, Java classes, XML files, tag libraries and static Web pages (HTML and related files) that together constitute a Web module.

• A WAR file contains what is known as a web module. It is the smallest deployable and usable unit of web resources.
• Web containers (Tomcat) and application servers (Glassfish) can both
• The top-level directory of a web module is the document root of the application. The document root is where JSP pages, client-side classes and archives, and static web resources, such as images, are stored.
• The document root contains a subdirectory named WEB-INF, which can contain the following files and directories:
  • classes: A directory that contains server-side classes: servlets, enterprise bean class files, utility classes, and JavaBeans components
  • tags: A directory that contains tag files, which are implementations of tag libraries
  • lib: A directory that contains JAR files that contain enterprise beans, and JAR archives of libraries called by server-side classes
  • Deployment descriptors, such as web.xml (the web application deployment descriptor) and ejb-jar.xml (an EJB deployment descriptor)

The structure of a WAR file looks like this:

The structure of a WAR file⁴.

Most real Web applications will use a web.xml file. It instructs the servlet container (e.g. Tomcat) on how to deploy and run the Web application. An example web.xml file is:

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE web-app
     PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
     "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
 
 <web-app>
     <servlet>
         <servlet-name>HelloServlet</servlet-name>
         <servlet-class>mypackage.HelloServlet</servlet-class>
     </servlet>
 
     <servlet-mapping>
         <servlet-name>HelloServlet</servlet-name>
         <url-pattern>/HelloServlet</url-pattern>
     </servlet-mapping>
 
     <resource-ref>
         <description>
             Resource reference to a factory for javax.mail.Session
             instances that may be used for sending electronic mail messages,
             preconfigured to connect to the appropriate SMTP server.
         </description>
         <res-ref-name>mail/Session</res-ref-name>
         <res-type>javax.mail.Session</res-type>
         <res-auth>Container</res-auth>
     </resource-ref>
 </web-app>

EAR: Enterprise ARchive

An EAR (Enterprise ARchive) file contains Java EE modules and, optionally, deployment descriptors. When a large Web application is deployed, all its .jar and .war files are packaged as JAR file with .ear extension and deployed into an application server.

• In addition to Web modules (WAR files), an EAR file can contain EJB modules (JAR), Application client modules (JAR) and Resource adapter modules (RAR).
• Deploying EAR files requires an application server such as Glassfish.
• Web containers such as Tomcat can not deploy EAR files, only WAR files.

EAR file structure⁵.

Sources

1. History of Web Frameworks
2. App server, Web server: What’s the difference?
3. Java EE Containers – The Java EE 5 Tutorial
4. Web Modules – The Java EE 6 Tutorial
5. Packaging Applications – The Java EE 6 Tutorial

Contents

• 1 1: Install Git
• 2 2: Configure Git
• 3 3: Generate Cryptographic Keys
• 4 4: Add Public Key To Github
• 5 5: Tell SSH to Use The New Key
• 6 6: Test Connection To Github
• 7 7: Clone a Repository And Start Coding

1: Install Git

sudo apt-get install git-core git-doc

2: Configure Git

Bare minimum:

git config --global user.name "Firstname Lastname"
git config --global user.email "myemail@gmail.com"

Enable colors when outputting to terminal:

git config --global color.ui true

These settings are saved in ~/.gitconfig.

3: Generate Cryptographic Keys

Create an RSA public/private key pair in the ~/.ssh/ directory. Be sure to use a passphrase.

ssh-keygen -t rsa -C "myemail@gmail.com" -f ~/.ssh/git_rsa

This generates a private key in ~/.ssh/git_rsa and the corresponding public key in ~/.ssh/git_rsa.pub

4: Add Public Key To Github

Copy all contents of ~/.ssh/git_rsa.pub and add it to your Github profile.

$ cat ~/.ssh/git_rsa.pub
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDJCqSW4MyOESvnNL6Xjc9jQ3Vvj+yZSqD+HB5Dcbewc3vKpUISaC4mnUetN2B0Xn5QUOVTwdfDti+N+uMHod5VTeDPN7jNdbA/b/Vjo+C+hdJ8tissJDaCSQ29Wluhlogoe/4H3uSWmwKvMkgnK6DK3rXBKdy/T6Xeb8iFlxK5LLUt1B5nv9wxOGlhLd6ul5VeVGZKYxdwRLRkWE1w+ffEnfhJualOOZrW71up2EYl/FnmOMCMA7oKRyje+uQ2XSai220MlMwFH/VSOFskEM9dmilRxtFv27cq1vasiAIloKwFP8uYh42P4m3FPbWMulNXZvA3F4YsDfTBfDzQ3SUt myemail@gmail.com

5: Tell SSH to Use The New Key

Git uses the ssh application to connect to Github. By default, ssh only tries to use the private key in ~/.ssh/id_rsa. We must tell it to also consider ~/.ssh/git_rsa for SSH authentication.

$ ssh-add ~/.ssh/git_rsa

This command requires that the ssh-agent daemon is running. If you can’t use ssh-agent, create the file ~/.ssh/config and add:

Host github.com
        User            git
        IdentityFile    ~/.ssh/git_rsa

6: Test Connection To Github

$ ssh -T git@github.com
Hi <user>! You've successfully authenticated, but GitHub does not provide shell access.

7: Clone a Repository And Start Coding

$ git clone git@github.com:username/myrepo.git

Contents

• 1 Introduction
• 2 Installing Subclipse
• 3 Connecting to Your Repository
• 4 Uploading a New Project to the Repository
• 5 Ignoring Files
• 6 Checking Out a Project From the Repository

Introduction

Any serious development effort requires some type of version control software such as Subversion (SVN). Eclipse has excellent SVN support through the Subclipse plugin. In this document we will see how a new Eclipse project can be checked into an SVN repository, and give some tips for organizing your repository.

If you are to learn one thing from this guide it is that you should think carefully about commiting IDE-specific files.

Installing Subclipse

First we install the Subclipse plugin into Eclipse to enable SVN support. This plugin includes the Subversion client, and integrates SVN into the Eclipse interface.

1) Open the Eclipse Marketplace through Help -> Eclipse Marketplace.

2) Search for Subclipse, and click Install.

3) Select all available Subclipse modules for installation, and accept the license agreement. Choose to restart Eclipse when prompted.

Connecting to Your Repository

With Subclipse installed we can now connect to an SVN repository, check out code, commit changes, and more of that good stuff. Subclipse provides several new views that will help us with these SVN tasks.

1) Go to Windows -> Views -> Other to open a list of all available views.  Notice that there is a new  “SVN” category. Open the SVN Repositories view from the SVN category.

2) Right-click in the SVN Repositories view, and select New -> Repository Location.

3) Enter the URL of your repository and click Finish.

Note that SVN supports multiple protocols for repository access, so the URL can have a http://, https:// or svn:// prefix. It’s a good idea to set up your SVN server to allow only https, since it is the most secure.

4) Now the repository should be available in the SVN Repositories view, and you can browse its contents. Our repository uses the standard organization with three top-level directories.

Uploading a New Project to the Repository

We have a project SimpleProject that we want to add to the repository.

1) Right-click the project and select Team -> Share Project.

2) Select SVN as the repository type.

3) Select the repository this project should be stored in.

4) Select the repository directory where the project should be stored, and click Finish.

The files in a repository are usually organized by project. A common convention is to store each project in a separate subdirectory of the /trunk directory in the repository. We will follow that convention, so the target location of SimpleProject is /trunk/SimpleProject.

5) Now the /trunk/SimpleProject directory is created in the repository, and the project is associated with this repository location in Eclipse. You can now commit (upload) your changes by right-clicking and selecting Team -> Commit.

Ignoring Files

When committing our simple project we see several Eclipse-specific files:

It is good practice to be conservative with uploading IDE-specific files to the repository. You have to think carefully about which files to check in. Using the svn:ignore property we can prevent files from being committed.

A common approach is to check in the .classpath and .project files, and to decide about files in the .settings on a per-file basis. For this example, however, we will use svn:ignore property to simply make all Eclipse files invisible to SVN.

1) Right-click your project and select Team -> Show Properties.

2) Right-click in the SVN Properties view and select Add a property.

3) Enter svn:ignore as the property name, and enter the names of the files you want to exclude from SVN. For this example we enter .project, .classpath and .settings. Click OK.

4) Commit your project using Team -> Commit. The IDE-specific files are no longer listed, so we can safely commit the rest of the project!

Two things are important to know:

• Properties in SVN are attributes of directories.
• Properties can be committed and checked out.

The property we just created is committed to the repository as an attribute of the /trunk/SimpleProject directory. If someone does a checkout of this project (I will show you how), it will automatically have the correct svn:ignore property.

A fast way of adding files to the svn:ignore property is by right-clicking and selecting Team -> Add to svn:ignore… This is only possible if the file is not in the repository yet–the option is greyed out otherwise. In that case you should first delete the file from the repository through the SVN Repositories view.

Checking Out a Project From the Repository

The downside of not storing IDE-specific files is that you need to do some extra work to start working on a project from the repository. Non-default settings, e.g. library classpaths, have to be configured manually after checking out the project.

When your projects start growing big, with lots of dependencies, you should really consider using a build tool such as Maven. You can safely store Maven’s pom.xml in the repository.

To check out a simple project from an SVN repository you can simple do this:

1) Go to SVN Repositories view and right-click the project directory. Select Checkout.

2) Select the option to check out using the New Project Wizard.

3) Select the type of project you want to create, in this case it is just a Java Project.

4) Configure the Java Project and click Finish.

Now finish setting up the project by adding any included the .jar files to your build path, and you should be good to go.

The Reference Sequence (RefSeq) collection aims to provide a comprehensive, integrated, non-redundant, well-annotated set of sequences, including genomic DNA, transcripts, and proteins. After downloading the latest release release from the FTP server, you end up with a lot of .gz files. An example of the filenames:

complete.1.1.genomic.fna.gz
complete.1.bna.gz
complete.1.genomic.gbff.gz
complete.10.bna.gz
complete.10.genomic.gbff.gz
complete.100.protein.gpff.gz

The README tells us that the filenames describe the type of information (genomic, protein, dna, rna). This information is split up in many (numbered) files. We are interested in protein information in the GenPept/GenBank Flat File format. Every file with protein information in this format has a name of the form complete.<number>.protein.gpff.gz.

Oh, and the regular expression for these filenames is:

^complete.[0-9]+.protein.gpff.gz$

Writing a parser for these files is a lot of work, but luckily we can use the BioJava framework to do the heavy lifting. We use version 1.8.1, which can be downloaded here. This example requires three .jar files are included in your Java project: core-1.8.1.jar, bytecode-1.8.1.jar and sequencing-1.8.1.jar.

The code below opens a given .gz file, e.g. complete.1.protein.gpff.gz,  and parses all protein entries:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

import java.io.BufferedReader;
import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.InputStreamReader;
import java.util.zip.GZIPInputStream;
 
import org.biojava.bio.BioException;
import org.biojava.bio.seq.ProteinTools;
import org.biojava.bio.seq.io.ParseException;
import org.biojava.bio.seq.io.SymbolTokenization;
import org.biojava.bio.symbol.IllegalSymbolException;
import org.biojavax.Namespace;
import org.biojavax.RichObjectFactory;
import org.biojavax.SimpleNamespace;
import org.biojavax.bio.seq.RichSequence;
import org.biojavax.bio.seq.io.GenbankFormat;
import org.biojavax.bio.seq.io.SimpleRichSequenceBuilder;
 
public void processFile(String fileLocation)
{
	// Open the .gz file in a BufferedReader
	GZIPInputStream gzipInputStream = null;
	BufferedReader fileIn = null;
	Reader decoder = null;
	try
	{
		gzipInputStream = new GZIPInputStream(new FileInputStream(fileLocation));
		decoder = new InputStreamReader(gzipInputStream, "UTF-8");
		fileIn = new BufferedReader(decoder);
 
	} catch (IOException e)
	{
		log.error("Error opening file with GZIPInputStream: " + fileLocation, e);
	}
 
	// Initialize the GenBank/GenPept flat file format parser
	GenbankFormat gf = new GenbankFormat();
	SimpleRichSequenceBuilder listener = new SimpleRichSequenceBuilder();
	Namespace gbSpace = (Namespace) RichObjectFactory.getObject(SimpleNamespace.class, new
			Object[]{"refseqNS"} );
	SymbolTokenization tokenization = null;
	try
	{
		// Tokenizer for the protein sequence. When parsing DNA you can use DNATools.getDNA().getTokenization("token")
		tokenization= ProteinTools.getAlphabet().getTokenization("token");
	} catch (BioException e)
	{
		log.error("Error creating tokenization from ProteinTools().", e);
	}
 
	// Parse all protein entries in the file.
	boolean hasNext = true;
	while (hasNext)
	{
		try
		{
			hasNext = gf.readRichSequence(fileIn, tokenization, listener, gbSpace);
			RichSequence entry = listener.makeRichSequence();
 
			// The protein sequence is now parsed and loaded into 'entry'.
			// Extract all the information you need here...
		} catch (IOException| BioException e)
		{
			log.error("Error reading RichSequence from RefSeq file.", e);
		}
	}
}

For more documentation on using the BioJava parsers check out this page on the BioJava wiki.

Example: We are parsing the file D:\homologene\build65\homologene.xml.

The first lines of the XML are:

<?xml version="1.0"?>
<!DOCTYPE HG-EntrySet PUBLIC "-//NCBI//HomoloGene/EN" "HomoloGene.dtd">
<HG-EntrySet>
  <HG-EntrySet_entries>
    <HG-Entry>
      <HG-Entry_hg-id>3</HG-Entry_hg-id>

We see a DOCTYPE declaration that points to a DTD file. DTD stands for Document Type Definition, and it is used to define the format of the XML file. The SAXParser will automatically look for this file in the same directory as the XML file.

When parsing we get the following error:

java.io.FileNotFoundException: D:\homologene\build65\HomoloGene.dtd (The system cannot find the file specified)
  at java.io.FileInputStream.open(Native Method)
  at java.io.FileInputStream.<init>(Unknown Source)
  at java.io.FileInputStream.<init>(Unknown Source)
  at sun.net.www.protocol.file.FileURLConnection.connect(Unknown Source)
  at sun.net.www.protocol.file.FileURLConnection.getInputStream(Unknown Source)
  at com.sun.org.apache.xerces.internal.impl.XMLEntityManager.setupCurrentEntity(Unknown Source)
  at com.sun.org.apache.xerces.internal.impl.XMLEntityManager.startEntity(Unknown Source)
  at com.sun.org.apache.xerces.internal.impl.XMLEntityManager.startDTDEntity(Unknown Source)
  at com.sun.org.apache.xerces.internal.impl.XMLDTDScannerImpl.setInputSource(Unknown Source)
  at com.sun.org.apache.xerces.internal.impl.XMLDocumentScannerImpl$DTDDriver.dispatch(Unknown Source)
  at com.sun.org.apache.xerces.internal.impl.XMLDocumentScannerImpl$DTDDriver.next(Unknown Source)
  at com.sun.org.apache.xerces.internal.impl.XMLDocumentScannerImpl$PrologDriver.next(Unknown Source)
  at com.sun.org.apache.xerces.internal.impl.XMLDocumentScannerImpl.next(Unknown Source)
  at com.sun.org.apache.xerces.internal.impl.XMLNSDocumentScannerImpl.next(Unknown Source)
  at com.sun.org.apache.xerces.internal.impl.XMLDocumentFragmentScannerImpl.scanDocument(Unknown Source)
  at com.sun.org.apache.xerces.internal.parsers.XML11Configuration.parse(Unknown Source)
  at com.sun.org.apache.xerces.internal.parsers.XML11Configuration.parse(Unknown Source)
  at com.sun.org.apache.xerces.internal.parsers.XMLParser.parse(Unknown Source)
  at com.sun.org.apache.xerces.internal.parsers.AbstractSAXParser.parse(Unknown Source)
  at com.sun.org.apache.xerces.internal.jaxp.SAXParserImpl$JAXPSAXParser.parse(Unknown Source)
  at loader.homologene.HomologeneParser.parseFile(HomologeneParser.java:95)
  at loader.homologene.HomologeneParser.parse(HomologeneParser.java:70)
  at loader.homologene.HomologeneMain.parse(HomologeneMain.java:33)

The reason for the error is that the DTD file does not exist on the filesystem.

To suppress this error and parse the XML without using the DTD, we override the default resolveEntity() function in the EntityResolver interface:

public class ParseTest implements DefaultHandler
{
  public void parse()
  {
    SAXParserFactory saxParserFactory = SAXParserFactory.newInstance();
    SAXParser saxParser = saxParserFactory.newSAXParser();
    saxParser.parse("D:\\homologene\\build65\\homologene.xml");
  }
 
  public InputSource resolveEntity(String publicId, String systemId)
  {
    return new InputSource(new ByteArrayInputStream("<xml version='1.0' encoding='UTF-8'>".getBytes()));
  }
 
  // ...other handler functions...
}

Now the file will be parsed without problems. Of course it is better to find and use the DTD file, so use this workaround at your own risk.