Skip Headers
Oracle® Java Embedded Suite Application Developer's Guide
Release 7.0
E28526-01
  Go To Table Of Contents
Contents

Previous
Previous
 
 

8 Samples

This is a chapter describes the code samples that are available with Oracle Java Embedded Suite.

Table of Contents

8.1 About the Samples

The samples are deliberately very simple in scope, analogous to the Hello, World examples written for many software products. They illustrate basic use of each component without the complication of doing useful application work. For example, the hellostorage sample (Section 8.4) creates a Java DB database of timestamps, adding one row each time it is invoked.

In addition to using the sample source code to learn about using the components, you can use a sample as a template for your own application, progressively modifying it to meet your application requirements.

If you are evaluating Oracle Java Embedded Suite, reviewing, and optionally running, the samples can give you a quick experience of the product's basic capabilities.

8.2 Sample Installation and Prerequisites

To read the samples code, you must install the Oracle Java Embedded Suite and its samples bundle as described in the Chapter 2. The most convenient way to explore the samples is as NetBeans projects, but you can also open the files with a text editor.


Note:

This chapter uses the notation $JES_HOME as shorthand for installDir/jes7.0/. The sample scripts automatically set and use the environment variable of the same name.


8.3 Sample Directories and Structure

The samples share a directory and have similar subdirectory structures.

8.3.1 samples Directory

The samples are located in $JES_HOME/samples/. This directory contains:

  • scripts/: Source code for bash shell scripts to run each sample, for example, hclient.sh for the HelloClient sample. These scripts take care of setting the classpath to include the required components and invoking the sample. They can be used as models for your own launch scripts. Do not run the scripts in this directory. Run the scripts in dist/run/.

  • build.xml: An umbrella Ant script that operates over all samples. Its targets are clean and build.

  • dist/: Created by the umbrella Ant script, dist/ contains application jar and war files, and the run/ directory from which you can invoke sample scripts.

8.3.2 Common Sample Structure

Each sample directory has a similar structure. The top directories and files are:

  • nbproject/: NetBeans project definition files and build-impl.xml, which is build specifications used by Ant and NetBeans.

  • build/: Build artifacts that can be ignored.

  • build.xml: Command line Ant build script. It imports nbproject/build-impl.xml which is the detailed build specifications. Editing build.xml is a convenient way to specify values for placeholder targets defined in nbproject/build-impl.xml.

  • dist/: Created by the build, contains the files for running the sample scripts.

  • src/: Source files contained in java/ and, for some samples, webapp/ subdirectories.

8.3.3 Running Samples

You must run samples from $JES_HOME/samples/dist/run/. Later sections of this chapter give details for each sample. You cannot run the samples in NetBeans.

In $JES_HOME/samples/dist/run/, the file config.sh defines environment variables that other scripts use. In particular, it defines classpaths for various combinations of components. This technique enables scripts to specify classpaths that minimize the runtime memory footprint by including only the components the script needs. For instance, a script that runs the JRE lightweight HTTP server does not need the GlassFish component.

config.sh also sets the runtime heap size to 64 megabytes (-Xmx64m option to the java command). This value is sufficient for the samples as they are defined, but it might limit your execution of samples with your own inputs. For example, specifying several large web applications to gfhost.sh (described in Section 8.5.3) might exhaust the default 64 megabyte heap. If the target device has more or less space for the heap, you can modify config.sh accordingly. When you run the samples on the host computer, you will get an OutOfMemoryError if you attempt to use more heap than the target device has.

To run samples on the target device, create a jes7.0/ directory on the target, then recursively copy $JES_HOME/samples/dist/ to the target's jes7.0/.

8.4 hellostorage Sample

This sample creates, updates, and displays a persistent database of timestamps. It adds a row each time main() is invoked.

8.4.1 Components

JRE, Java DB (embedded JDBC driver only, see Section 8.4.4)

8.4.2 Source Files

Location: $JES_HOME/samples/hellostorage/

Description: HelloStorage.java is the complete sample. See Figure 8-1 for an overview.

Figure 8-1 Overview of hellostorage Sample Files

Surrounding text describes Figure 8-1 .

In more detail, the program:

  • Loads the Embedded Driver from JavaDB.

  • Creates a JDBC connection for 'hello' database.

  • If this is the first run, creates a 'history' table which contains id & timestamp columns.

  • Inserts the current timestamp into the history table (id is auto-generated).

  • Queries the history table & prints all the contents indicating the list of timestamps when this program was run (sorted by id).

  • Closes the JDBC connections.

  • Shuts down the database.

8.4.3 Run Instructions and Sample Output

Bold type indicates user input.

$ cd $JES_HOME/samples/dist/run 
$ ./hstorage.sh 
Hello World from JavaDB!
    Hello #1 @ 2012-05-10 11:21:17.164
$ ./hstorage.sh 
Hello World from JavaDB!
    Hello #1 @ 2012-05-10 11:21:17.164
    Hello #2 @ 2012-05-10 11:21:25.988
$

8.4.4 Notes

  • The sample does not use Java DB APIs, and can therefore be compiled without derby.jar in the classpath. However, derby.jar must be specified in the runtime classpath because it supplies the embedded JDBC driver.

  • The first run, which creates the database, can take on the order of 10 seconds to complete. Subsequent runs are faster.

  • The database is created in the directory in which you launch the sample. The database files are stored in a subdirectory named hello/. You can inspect the database with $JES_HOME/javadb/bin/ij.

  • You can delete the database with rm -rf hello.

8.5 webhost Sample

The webhost sample is a utility that provides common interfaces for running applications on either GlassFish or the JRE's lightweight HTTP server. It implements a management lifecycle, starting the server, deploying one or more applications, undeploying applications, and stopping the server.

If you have existing web applications that run on standalone application servers, the webhost utility can help you get them running on the embedded GlassFish server included with Oracle Java Embedded Suite.

If you have annotation-based JAX-RS (Jersey) applications, you can use webhost to deploy them on the lightweight HTTP server. See the HelloService (Section 8.7) and hellosuite (Section 8.9) samples for examples of Jersey applications supported by webhost. The lightweight HTTP server's memory footprint is much smaller than GlassFish's.

8.5.1 Components

Jersey, GlassFish, JRE (notably com.sun.net.httpserver)

8.5.2 Source Files

Location: $JES_HOME/samples/webhost/

Descriptions: See Figure 8-2 for an overview.

  • WebHost.java: An abstract class that defines an interface to, and partial implementation of, a generic webhost.

  • GlassFishHost.java: Implements a webhost with the embedded GlassFish application server (org.glassfish.embeddable APIs) to deploy web applications packaged in WAR files. There are other ways to deploy a GlassFish application, but GlassFishHost.java does not support them.

  • LightweightHost.java: Implements a webhost with the JRE lightweight HTTP server, deploying applications packaged in JAR files by creating a handler and context for each. It supports only annotation-based JAX-RS applications, but could be modified to support other styles of Jersey applications.

Figure 8-2 Overview of webhost Sample Files

Surrounding text describes Figure 8-2 .

8.5.3 Run Instructions

The scripts gfhost.sh and lwhost.sh, respectively, launch the GlassFish and lightweight webhosts. For a lightweight webhost example, see Section 8.7.3. For the GlassFish webhost, see Section 8.6.3.

8.5.4 Notes

  • To compile the webhost sample, specify glassfish-jes.jar in the classpath.

  • To run the GlassFish webhost, include glassfish-jes.jar in the classpath (gfhost.sh does this automatically). The lightweight webhost has no classpath requirement.

8.6 helloservlet Sample

helloservlet illustrates the Servlet 3.0 application lifecycle, running in a GlassFish container. (The lightweight HTTP server does not support servlets.)

8.6.1 Components

GlassFish, JRE

8.6.2 Source Files

Location: $JES_HOME/samples/helloservlet/

Description: For an overview, see Figure 8-3. The code is very simple, defining the context for the servlet ("/"), and a doGet() method that returns a string.

Figure 8-3 Overview of helloservlet Sample Files

Surrounding text describes Figure 8-3 .

8.6.3 Run Instructions and Example Output

Bold type indicates user input.

  1. Start the servlet in the GlassFish webhost with the gfhost.sh script (described in Section 8.5)

    $ cd $JES_HOME/samples/dist/run
    $  ./gfhost.sh ../helloservlet.war
    Preparing to run glassfish host...
    May 11, 2012 1:57:44 PM com.sun.enterprise.v3.server.CommonClassLoaderServiceImpl findDerbyClient
    INFO: Cannot find javadb client jar file, derby jdbc driver will not be available by default.
    May 11, 2012 1:57:45 PM org.hibernate.validator.util.Version <clinit>
    INFO: Hibernate Validator 4.2.0.Final
    May 11, 2012 1:57:46 PM com.sun.enterprise.v3.services.impl.GrizzlyService createNetworkProxy
    ...
    Here is the list of installed apps:
        helloservlet
    Please visit following URL(s)to verify app(s)
        http://IPaddr:8080/<ROOT>/[<URI>]
    Please refer to app docs for the context ROOT & URI
    Press <Enter> to exit server
    
  2. In a web browser, enter the IP address given near the end of the output with the web application name, for example, http://IPaddr:8080/helloservlet. The servlet response is similar to Figure 8-4.

    Figure 8-4 Output from helloservlet Sample

    Surrounding text describes Figure 8-4 .
  3. Stop the servlet by pressing <Enter> in the shell in which you launched gfhost.sh.

    Undeploying: helloservlet
    PlainTextActionReporterSUCCESSNo monitoring data to report.
    Stopping server com.sun.enterprise.glassfish.bootstrap.StaticGlassFishRuntime$1@1b6d9cf
    May 11, 2012 2:27:52 PM com.sun.enterprise.v3.server.AppServerStartup stop
    INFO: Shutdown procedure finished
    May 11, 2012 2:27:52 PM AppServerStartup run
    INFO: [Thread[GlassFish Kernel Main Thread,5,main]] exiting
    

8.6.4 Notes

Unlike the RESTful service described in Section 8.7, helloservlet is not accessible from a Java program, only a web browser.

8.7 helloservice Sample

helloservice is a simple RESTful service that returns HTML text to a web browser client, or a bean to a Java program client. The service can be deployed on the GlassFish or lightweight webhost (see Section 8.5).

8.7.1 Components

Jersey and either GlassFish or JRE lightweight HTTP server

8.7.2 Source Files

Location: $JES_HOME/samples/helloservice/

Descriptions: See Figure 8-5 for an overview.

  • HelloApplication.java: Extends the JAX-RS Application class whose single getClasses() method defines the application resources, in this case, the HelloService class.

  • HelloService.java: The service's main handler, it defines two JAX-RS GET operations. One returns HTML text to browser clients. The other returns a Java object (a bean) to Java clients.

  • HelloBean.java: This class implements the bean that HelloService returns to Java clients.

Figure 8-5 Overview of helloservice Sample Files

Surrounding text describes Figure 8-5 .

8.7.3 Run Instructions and Sample Output

The following instructions deploy the helloservice sample on the lightweight webhost, using lwhost.sh. In these instructions, you use two shells, one to launch the service, the other to run client invocations. You also invoke the service from a web browser.

Bold type indicates user input.

  1. Start the lightweight webhost running the helloservice RESTful service:

    $ cd $JES_HOME/samples/dist/run 
    $ ./lwhost.sh ../helloservice.jar  com.oracle.jes.samples.helloservice.HelloApplication 
    Preparing to run lightweight host...
    Deploying: ../helloservice.jar
    May 11, 2012 3:25:50 PM com.sun.jersey.server.impl.application.WebApplicationImpl _initiate
    INFO: Initiating Jersey application, version 'Jersey: 1.11.1 03/31/2012 06:49 PM'
    Here is the list of installed apps:
        helloservice
    Please visit following URL(s)to verify app(s)
        http://IPaddr:8080/<ROOT>/[<URI>]
    Please refer to app docs for the context ROOT & URI
    Press <Enter> to exit server. 
    

    To deploy on the GlassFish webhost, substitute ./gfhost.sh ../helloservice.war for ./lwhost.sh ../helloservice.jar.

  2. Invoke the service from a web browser client using the IP address given near the end of the lwhost output, for example, http://IPaddr:8080/helloservice. The service responds similarly to Figure 8-6.

    Figure 8-6 Browser Client Output from helloservice Sample

    Surrounding text describes Figure 8-6 .
  3. Stop the service by pressing <Enter>.

    undeploying: helloservice
    

8.8 helloclient Sample

The helloclient sample creates a RESTful client and invokes helloservice (described in Section 8.7) as specified by hclient.sh's two arguments, type and URL. The type argument values are "text," "html", "xml", and "json" (all lower case or upper case). The URL argument identifies helloservice.

There is an alternative "type", which gets a bean object from the service. For this case, the type is the name of the bean class, the URL identifies the service, and a third argument is the JAR file on the classpath that contains the bean class.

This client can also used with the hellosuite sample (see Section 8.9).

8.8.1 Components

Jersey (client and server)

8.8.2 Source Files

Location: $JES_HOME/samples/helloclient/

Description: See Figure 8-7 for an overview. The single source file is HelloClient.java, which creates the Client and then executes a switch based on the type argument.

Figure 8-7 Overview of helloclient Sample Files

Surrounding text describes Figure 8-7 .

8.8.3 Run Instructions and Sample Output

These instructions demonstrate how to use helloclient to obtain a helloservice result in JSON format and as a bean object.

Bold type indicates user input.

  1. Launch helloservice as described in Section 8.7.3.

  2. In a second shell, launch helloclient specifying a type of JSON.

    $ cd $JES_HOME/samples/dist/run 
    $ ./hclient.sh JSON http://IPaddr:8080/helloservice 
    {"text":"Hello World from JAX-RS!"} 
    
  3. In the second shell, launch helloclient, asking for the result in a HelloBean object.

    $ cd $JES_HOME/samples/dist/run 
    $ ./hclient.sh com.oracle.jes.samples.helloservice.HelloBean http://IPaddr:8080/helloservice ../helloservice.jar
    [Hello World from JAX-RS!] 
    
  4. In the first shell, terminate helloservice by pressing <Enter>.

8.8.4 Notes

If you use the bean object option, the JAR containing the bean class must be included in the classpath. The hclient.sh script adds the third argument (../helloservice.jar in Section 8.8.3) to the classpath. To keep helloclient simple, the bean class is in helloservice.jar. A real application would likely define the bean in a separate JAR file included in both the client and server class paths.

8.9 hellosuite Sample

The hellosuite sample illustrates all of the Oracle Java Embedded Suite components used in combination. The sample is a Jersey RESTful service that runs in a GlassFish or lightweight HTTP container and stores data in a Java DB database.

8.9.1 Components

Jersey, Java DB, GlassFish, JRE (in particular, the lightweight HTTP server)

8.9.2 Source Files

Location: $JES_HOME/samples/hellosuite/

Description: See Figure 8-8 for an overview.

  • HelloApplication.java: Extends the JAX-RS Application class whose single getClasses() method defines the application resources, in this case, the HelloService class.

  • HelloBean.java: This class implements the bean that HelloSuite returns to Java clients.

  • HelloStore.java: This class handles persistence with Java DB. It creates the database, adds timestamp rows, lists the contents of a particular row or all rows.

  • HelloSuite.java: This is the service class. It defines these contexts for the service URL:

    • /: Adds a timestamp row to the database and returns "Hello world from JES!" as text or HTML.

    • /count: returns the number of database rows as text.

    • /list: lists the database records in XML or JSON format.

    • /id: Returns the database record indexed by id in XML or JSON format. The first record has an id of 1. This illustrates taking an input parameter from the client.

Figure 8-8 Overview of hellosuite Sample Files

Surrounding text describes Figure 8-8 .

8.9.3 Run Instructions and Sample Output

The following instructions use the GlassFish webhost. To use the lightweight webhost, see Section 8.9.4.

You use two shells in these instructions, the first to run the hellosuite service, the second to launch clients that use the service. If you have run this sample or hellostorage previously, you might want to remove the old database before running this sample. Existing database timestamps are potentially confusing. Remove the old database as follows:

$ cd $JES_HOME/samples/dist/run 
$ rm -rf hello 
 

Bold type indicates user input.

  1. In a shell, start the hellosuite service:

    $ cd $JES_HOME/samples/dist/run 
    $ ./gfhost.sh ../hellosuite.war 
    Preparing to run glassfish host...
    May 17, 2012 1:47:08 PM com.sun.enterprise.v3.server.CommonClassLoaderServiceImpl findDerbyClient
    ...
    INFO: hellosuite was successfully deployed in 4,006 milliseconds.
    Here is the list of installed apps:
        hellosuite
    Please visit following URL(s)to verify app(s)
        http://IPaddr:8080/<ROOT>/[<URI>]
    Please refer to app docs for the context ROOT & URI
    Press <Enter> to exit server.
    
  2. In a web browser, enter the IP address given near the end of the gfhost output (shown in italic type above) with the service name: http://IPaddr:8080/hellosuite. The service response is similar to Figure 8-9.

    Figure 8-9 Browser Client Output for hellosuite Sample

    Surrounding text describes Figure 8-9 .
  3. In the web browser, enter a URL similar to http://IPaddr:8080/hellosuite/count. The browser displays a count of 1 similar to Figure 8-10.

    Figure 8-10 Browser Client Output for hellosuite/count

    Surrounding text describes Figure 8-10 .
  4. Repeat step 2 a few times to direct the service to add timestamp rows to the database.

  5. Repeat step 3 to get a count of the current number of rows in the database.

  6. In the web browser, enter http://IPaddr:8080/hellosuite/list to see an XML list of the database records.

  7. In the web browser, enter http://IPaddr:8080/hellosuite/3 to see an XML display of the third record.

  8. In a second shell, run helloclient to lists the database records in JSON format. The results are similar to the following (ignore line breaks).

    $ cd $JES_HOME/samples/dist/run 
    $ ./hclient JSON http://localhost:8080/hellosuite/list 
    {"helloBean":[{"id":"1","time":"2012-05-17 15:28:32.749"},{"id":"2","time":"2012-05-17 18:06:17.285"},{"id":"3","time":"2012-05-17 18:06:21.968"},{"id":"4","time":"2012-05-17 18:06:24.049"}]}
    $
    
  9. In the second shell run helloclient to list the first (or other) database record as a bean.

    $ ./hclient.sh com.oracle.jes.samples.hellosuite.HelloBean http://localhost:8080/hellosuite/1 ../hellosuite.jar 
    [ 1# 2012-05-17 15:28:32.749 ]
    
  10. In the first shell, press <Enter> to terminate the service.

8.9.4 Notes

  • The sample does not use JavaDB APIs, and can therefore be compiled without derby.jar in the classpath. However, derby.jar must be specified in the runtime classpath because it supplies the embedded JDBC driver.

  • The first invocation, which creates the database, can take on the order of 10 seconds to complete. Subsequent runs are faster.

  • The database is created in the directory in which you launch the sample. The database files are stored in a subdirectory named hello/. You can inspect the database with $JES_HOME/javadb/bin/ij.

  • You can delete the database with rm -rf hello.

  • You can run the service with the lightweight webhost instead of GlassFish, by making this step 1:

    $ ./lwhost.sh ../hellosuite.jar com.oracle.jes.samples.hellosuite.HelloApplication