Copyright (c) 2005 The Apache Software Foundation or its licensors, as applicable.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

 

     http://www.apache.org/licenses/LICENSE-2.0

 

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

 

Kevin Williams

V-0.4

Tuscany RDB DAS Sample (companyweb)

 

 

This stand-alone sample demonstrates the SDO RDB Data Access Service in the context of a simple web application.

 

The application starts with a canned database of Companies and their related Departments.  Through the web page interface, a user can:

 

  1. Display all Companies in the database
  2. Display all Companies and related Departments
  3. Add a new Department to a Company
  4. Delete all Departments from a Company
  5. Change the names of Departments in a Company

 

So, this simple application covers all CRUD operations as well as the some relationship manipulation (adding a Department associates that Department with the Company).  The sample runs on Tomcat 5.5 and employs a Derby database accessed via a DataSource.

 

Running the sample

There are three options for running this sample:

 

  1. Run from Tomcat in the binary distribution
  2. Run from Tomcat configured by the build
  3. Run from Tomcat you configure yourself

Running from binary distribution

This sample is also pre-deployed in a Tomcat instance as part of the Tuscany binary distribution.  When running the sample this way, you just:

  • Unzip the distribution archive
  • Change the directory to  apache-tomcat-5.5.17\bin
    • If you start Tomcat from some other location then it will not find the canned database
  • Execute: startup
  • Point your browser to http://localhost:8080/sample-companyweb/

Running from Tomcat configured by the build

This sample application is deployed (along with the canned test database) to an instance of Tomcat as part of our automated sample testing.  This means you can run the java/testing/tomcat build (see java/testing/tomcat/readme.htm )  and then access the application by pointing your browser to http://localhost:8080/sample-companyweb/. 

Running from Tomcat you configure yourself

Alternatively, you can deploy the sample to your own configured Tomcat installation by following the instructions below.  These instructions assume that you have downloaded the Tuscany source and run our maven build.  https://svn.apache.org/repos/asf/incubator/tuscany/java/BUILDING.txt

Set Up

  1. Download and install the most recent stable version of Tomcat 5.5.  You can find it here: http://tomcat.apache.org/download-55.cgi
  2. Download the most recent official release of Derby from here: http://db.apache.org/derby/index.html.  The only file you’ll need from this download is derby.jar
  3. Stop Tomcat
  4. Move the following files (details in appendix) to {Tomcat_Home}/common/lib:
    1. tuscany-das-rdb-xxx.jar
    2. sdo-api-xxx.jar
    3. tuscany-sdo-impl-xxx.jar
    4. xsd{latest version}.jar
    5. ecore-{latest version}.jar
    6. ecore-change-{latest version}.jar
    7. ecore-xmi-{latest version}.jar
    8. common-{latest version}.jar
    9. derby.jar
  5. Add the sample war file (details in appendix) to {Tomcat_Home}/webapps
    1. sample-companyweb-xxx.war
  6. Install the canned Derby database to Tomcat:
    1. Create {Tomcat_Home}/Databases
    2. Copy the dastest folder (and all its contents) from {build directory root}/java/samples/das/companyweb to {Tomcat_Home}/Databases.  
  7. Define a DataSource by adding a datasource definition to {Tomcat_Home}/conf/server.xml.
    1. Find the end-of-section marker </GlobalNamingResources> and add the following lines just above it:

 

        <!-- Global Datasource for Derby dastest database -->
         <Resource name="jdbc/dastest"
              type="javax.sql.DataSource"  auth="Container"
              description="Derby database for DAS Company sample"
              maxActive="100" maxIdle="30" maxWait="10000"
              username="" password="" 
              driverClassName="org.apache.derby.jdbc.EmbeddedDriver"
              url="jdbc:derby:Databases/dastest"/>

 NOTE: If you are NOT starting Tomcat as a service then you will need to provide the absolute path in the above url.  Fore example:

 

         url="jdbc:derby:c:\apache-tomcat-5.5.17\Databases/dastest"/>

 

  1. Start tomcat and either:

go to the manager console http://localhost:8080/manager/html and select the application named “Tuscany DAS sample Company WEB”

or:

point your browser to :

http://localhost:8080/sample-companyweb-{version name}/

 

NOTE: for the M1 version of Tuscany sample the url is:

http://localhost:8080/sample-companyweb-incubating-M1/

 

Sample Architecture

This is a simple, single-page, web application.  The main components of this application are:

  • The RDB Data Access Service (DAS)
  • SDO
  • CompanyClient.java
  • Company.jsp
  • The canned Derby database

 

 

The CompanyClient uses the DAS directly and provides high-level services to the jsp such as:

public final List getCompanies()

This is a good place to look for how you might use the DAS in your own application.

 

The Company.jsp responds to client interaction by invoking services of the CompanyClient.  It receives data from the CompanyClient as SDO data graphs and manipulates SDOs directly to display data.

 

The canned Derby database comes preloaded with Companies and related Departments.  The Derby database instance is a simple file folder.

 

The DAS accepts directives (commands) from the CompanyClient and reads and writes to the derby database instance appropriately.

 

Appendix

 

The following specifies the location of all dependency jars needed to run this sample.  These jars are available only after you have successfully downloaded and built Tuscany/java.  Instructions for building can be found here:

https://svn.apache.org/repos/asf/incubator/tuscany/java/BUILDING.txt

 

Dependency jar locations:

 

For Step #4

  • tuscany-das-rdb-xxx.jar – {build directory root}/java/das/rdb/target
  • sdo-api-xxx.jar – {build directory root}/java/spec/sdo/target
  • tuscany-sdo-impl-xxx.jar – {build directory root}//java/sdo/impl/target
  • xsd{latest version}.jar – {user}/.m2/repository/org/eclipse/xsd
  • ecore-{latest version}.jar – {user}/.m2/repository/org/eclipse/emf/ecore
  • ecore-change-{latest version}.jar – {user}/.m2/repository/org/eclipse/emf/ecore-change
  • ecore-xmi-{latest version}.jar  – {user}/.m2/repository/org/eclipse/emf/ecore-xmi
  • common-{latest version}.jar  – {user}/.m2/repository/org/eclipse/emf/common
  • derby.jar – Extract from the archive file you downloaded in step #2

 

Application artifact locations:

 

For Step #5

  • sample-companyweb-xxx.war - {build directory root}/java/samples/das/companyweb/target

 

Conventions:

  • {user} refers the directory where Maven2 is installed on your machine.  On my machine, “{user}” is “C:\Documents and Settings\Administrator”
  • {Tomcat_Home} refers to the directory that Tomcat is installed on your machine.  On my machine, this is “C:\Program Files\Apache Software Foundation\Tomcat 5.5”
  • {latest version} means the tag associated with the latest version available in the maven2 repository.  For example the version of ecore-{latest version}.jar that I used for testing this sample is “ecore-2.2.0-RC4.jar”
  • {build directory root} refers to the target directory for the tuscany/java source you are building from