Cloud: Java Cloud Service SDK

#

## Sample Introduction

This sample emulates a simple online shopping application. It provides a book catalog from which you can select books and add them to a shopping cart. You can view and modify the shopping cart. When users are finished shopping, you can purchase the books in the cart uses. The application shares common classes and a database schema which are packaged into a JAR by project: `SDK_HOME/samples/ee5/bookstore` (where `SDK_HOME` is the directory containing your Java Cloud Service installation), so this JAR file must be included in the application's WAR file during sample building.

This application illustrates the tasks involved in programming servlets, focuses on writing servlets that generate responses to HTTP requests. The data for the bookstore application is maintained in a database and accessed through the database access class `database.BookDBAO`. The database package also contains the class Bookm which represents a book. The shopping cart and shopping cart items are represented by the classes `cart.ShoppingCart` and `cart.ShoppingCartItem`, respectively.

For details about the example code, see the files that are listed in the following table.

## Main Files Used in the Sample

Directory Location:

SDK_HOME/samples/ee5/bookstore1

(where SDK_HOME is the directory containing your Oracle Java Cloud installation)

File Click source files to view code. | Description
--- | ---
build.xml | Ant build file that contains targets for building, deploying, and running the sample.
BookDBAO.java | Database Access Object class that provides common database operations on the Book entity.
CharResponseWrapper.java | A `HttpServletResponseWrapper` class that wrappers the servlet response with a `CharArrayWriter`.
HitCounterFilter.java | Java servlet filter class that increments and log the value of hit counter when the entry and receipt servlets are accessed, and inserts it into the servlet response.
OrderFilter.java | Java servlet filter class that increments and log the value of order counter when the entry and receipt servlets are accessed, and inserts it into the servlet response.
ContextListener.java | Java `ServletContextListener` class that creates and/or removes the database access and counter objects in servlet context.
BannerServlet.java | Java Servlet class that creates the common bookstore banner for all the servlets in the application.
BookDetailsServlet.java | Java Servlet class that generates an HTML page that displays detailed information on a specific a book that the servlet retrieves from a database.
BookStoreServlet.java | Java servlet class that provides access to the bookstore.
CashierServlet.java | Java servlet class that generates a form and retrieves the total cost of the books in the shopping cart.
CatalogServlet.java | Java servlet class that browses the bookstore catalog and puts a book in a shopping cart.
ReceiptServlet.java | Java servlet class that sends an acknowledgment of the purchase.
ShowCartServlet.java | Java servlet class that displays the shopping cart and removes one or more books from the shopping cart.
Counter.java | Counter object class that can be set and read by multiple multi-threaded servlets.
Currency.java | Currency object class that can be set and read by multiple multi-threaded servlets.
errorpage.html | HyperText Markup Language page responses to the application errors or exceptions.
web.xml | Web application deployment descriptor that maps the FacesServlet.
weblogic.xml | Oracle WebLogic Server-specific Web application deployment descriptor that declares the application context root.

## Prepare the Sample

### Prerequisites for Deploying the Sample Locally

1. Install Oracle WebLogic Server and configure it. This is required only if you want to deploy applications locally
2. In the `SDK_HOME/samples/myenv.*` script, set the MW_HOME environment variable to the directory where WebLogic Server is installed.
3. Run the script:
   - On Linux, run: `. ./myenv.sh`
   - On Windows, run: `myenv.cmd`
4. Set the following environment variables in the `SDK_HOME/samples/build.common.properties` properties file:
   - set local to true, the default value is false.
   - set identity-domain to the identity domain name where you will deploy the application.
   - set service-instance to the service instance name where you will deploy the application.
   - set local-admin-url to the URL of the local WebLogic admin server.
   - set local-admin-user to the admin user who has permission to deploy the application.
   - set data-source to the data source name that the application will use to do database operations.

You can also refer to Preparing Applications for Java Cloud Service Deployment in Using Oracle Java Cloud Service and the sample main page for more details.

### Prerequisites for Deploying the Sample on Java Cloud Service

If you are going to install your application only on a remote Java Cloud Service instance, you will not need to have WebLogic Server installed locally. Just make sure that "ant" and "javac" are available in the path.

Set the following environment variables in the `SDK_HOME/samples/build.common.properties` properties file:

- set identity-domain to the identity domain name where you will deploy the application.
- set service-instance to the service instance name where you will deploy the application.
- set cloud-admin-url to the admin URL that is used to deploy the application on Oracle Cloud.
- set cloud-admin-user to the admin user who has permission to deploy the application on Oracle Cloud.
- set data-source to the data source name that the application will use to do database operations.

## Build and Deploy the Sample

To build the sample, follow these steps:

1. Change to the `SDK_HOME/samples/ee5/bookstore1` directory, where SDK_HOME refers to the main Java Cloud Service SDK installation directory, such as `/home/user/oracle-javacloud-sdk`.
2. Execute the following command in the shell. (If you deploy the sample to local environment, choose the shell where you run the `myenv.*` script.)
   `ant clean`
   This command cleans the build directory.
   `ant build`
   This command compiles and stages the sample.
3. Execute the following command in the shell. (If you deploy the sample to local environment, choose the shell where you run the `myenv.*` script.)
   `ant install`
   This command installs the sample on the local WebLogic Server or remote Java Cloud Service.

The Ant command uses the `build.xml` file in the `SDK_HOME/samples/ee5/bookstore1` directory to build the sample.

## Run the Sample

1. Complete the steps in the "Prepare the Sample" section.
2. Execute the following command in the shell. (If you deploy the sample to local environment, choose the shell where you run the `myenv.*` script.)
   `ant run`
   This command tries to automatically launch the web browser with the URL pattern `http://server:port/bookstore1`, where the server would include the identity domain and service instance name. For example, `https://java1-wnctrial.java.dc1.c9labga.us.oracle.com/bookstore1`, where `java1` is the service instance name and `wnctrial` is the identity domain. The rest of the host name `java.dc1.c9labga.us.oracle.com` is based on the environment. The actual URL should be printed when you run the samples.
   If the above does not work, you can open a browser, then copy and paste the above URL.
   For non-Windows and non-Mac machines, make sure that you have specified valid browser for the `default.browser` property in `SDK_HOME/samples/build.common.properties.`