Fabric3 is a platform for developing, assembling, and managing distributed applications. Fabric3 provides the following features:
In this chapter, we cover the basics of setting up and deploying an application using Fabric3. Subsequent chapters will cover developing loosely-coupled services, runtime configuration and topics such as integration with Java Persistence Architecture (JPA).
This manual assumes a basic understanding of SCA concepts. Before proceeding, if you have not done so, we recommend familiarizing yourself with SCA. The specifications themselves (downloadable from {+}http://www.oasis-opencsa.org/+) are generally not the most accessible source of introductory information. We recommend instead the paper by David Chappell, "Introducing SCA" ({+}http://www.davidchappell.com/articles/Introducing_SCA.pdf+), which presents a balanced and accurate overview of SCA. Alternatively, Jim Marino and Michael Rowley, Understanding SCA (Addison-Wesley) provides an in-depth treatment including Fabric3.
The runtime image is organized as:
/bin |
|
|
|
|
Startup modules |
|
/lib |
|
|
|
|
Modules required to start the runtime host |
|
/boot |
|
|
|
|
Modules required for the runtime bootstrap and primordial system services |
|
/host |
|
|
|
|
Libraries shared between the runtime and application (e.g. web services annotations) |
|
/extensions |
|
|
|
|
Extension modules that are able to be loaded by all runtime instances |
|
/runtimes |
|
|
|
|
Specific runtime instance configuration is hosted by default under this directory |
|
|
<runtime-name> |
|
|
top level directory for a runtime configuration |
|
|
|
|
/config |
|
|
Contains systemConfig.xml for configuring the runtime and extensions |
|
|
|
/deploy |
|
|
File system deploy directory for the controller and single-VM runtimes |
|
|
|
/repository |
|
|
|
|
|
|
|
/runtime |
|
Extensions only loaded for the runtime image |
|
|
|
|
/user |
|
User contributions (only populated on the controller and single-VM runtimes) |
|
|
|
/data |
|
|
Persistent data directory for a runtime instance (e.g. transaction log) |
|
|
|
/tmp |
|
|
Temporary data and artifact cache for a runtime instance |
|
For basic startup, the runtime name is required, which maps to a configuration under runtimes:
java -jar server.jar controller |
launches a runtime using the runtimes/controller image |
java -jar server.jar vm |
launches a runtime using the runtimes/vm image |
java -jar server.jar participant |
launches a runtime using the runtimes/participant image |
java -jar server.jar foo |
launches a custom runtime using the runtimes/foo image |
The samples are intended to demonstrate the capabilities of Fabric3 using the standalone or Tomcat distributions. The samples contain individual applications designed to showcase specific features and are organized as follows:
For projects that intend to use Spring, Fabric3 also ships with a set of dedicated Spring samples. These samples are ports of the SCA Java samples described in this chapter, with SCA Java components replaced by Spring beans. Basic layout, configuration and deployment remain the same across both sets of samples.
The samples may be downloaded from {+}http://www.fabric3.org/downloads+ and require the following software:
Note that it is not necessary to download the Fabric3 runtime distribution in addition to the samples as the sample build process will automatically download a distribution and configure a Fabric3 runtime cluster.
The starter calculator applications are the recommended way to get familiar with Fabric3. To build and deploy the calculator applications, do the following:
In the directory where you extracted the samples distribution, go to the /starter project folder and execute:
mvn clean install
#
Note internet access is required the first time the project is built so Maven can download the required project dependencies. Remote access can be turned off for subsequent builds by executing:
mvn -o clean install
JARs containing the application artifacts will be created in the /target output directories for each application.
Download the Fabric3 standalone runtime by executing the Maven build script from the samples /servers/vm directory:
mvn -o clean install
This will create a server image for use with the samples in the /target/image directory. Note the server is configured to run as a single instance. The /servers/cluster directory contains modules which will configure a multi-cluster Fabric3 installation. The starter applications can be deployed to either topology.
To launch a Fabric3 server in single-VM mode, execute the following from the /bin directory /servers/vm/target/image by executing:
java -jar server.jar
Alternatively, the Fabric3 server can be started from another working directory by executing:
java -jar <path to bin directory>server.jar
After the server has booted, deploy a calculator application archive by copying it to the Fabric3 runtime /deploy directory.
The runtime will write a message to the console after the war has been deployed. Depending on the application deployed, one of the following will be available.
http://localhost:8181/ calculator/entry.html.
http://localhost:8181/calculator/1+1
http://localhost:8181/calculator
and its WSDL from:
http://localhost:8181/calculator?wsdl
The samples also contain a separate client for the web services calculator. The client module is located at /samples/wscalc-client. The WSCalcClient class can be executed using the Java command line or via an IDE.
To build and deploy BigBank, do the following:
To build BigBank, go to the bigbank project folder and execute:
mvn clean install
The build will produce two archives: bigbank-loan-1.7.jar (the server module) and bigbank-client-1.7.jar (the web service client)
Boot the Fabric3 runtime from the server/vm/image/bin directory by executing:
java -jar server.jar
Copy bigbank-loan-1.7.jar to the runtimes/vm/deploy directory.
BigBank includes a web application front-end and loan officer web application. Note both web applications currently do not support Internet Explorer. Please use FireFox, Chrome, or Safari.
Copy bigbank-web-1.7.jar and bigbank-backoffice-1.7.jar to the runtimes/vm/deploy directory.
The samples distribution also contains an automated build process for producing a set of clustered servers. To create the clustered servers, execute the following from the servers/cluster directory:
mvn clean install
The build will create three server images located in the target directory of each module under /servers/cluster: controller, zone1, and zone2.
Follow the steps in the previous section to build the BigBank application. When the build completes, launch the H2 database, controller and zone runtimes:
java -jar target/h2-1.2.140.jar
java -jar server.jar controller
java -jar server.jar participant
java -jar server.jar participant
After booting, the runtimes will discover each other and form a distributed domain consisting of two cluster zones. Note the runtimes may be on the same machine or different machines.
Copy bigbank-loan-1.7.jar to the controller/target/image/runtimes/controller/deploy directory. The controller will provision the loan service to zone1 and the backend services to zone2.
To run additional zone participants, copy one of the images and follow the instructions above for launching the servers. If more than one server is run on the same machine, you will need to modify the HTTP and HTTPS ports in config/participant/systemConfig.xml.
At some point you may require help with Fabric3. The best place to obtain pointers, advice or assistance troubleshooting a problem is the user mailing list, which can be accessed at {+}http://xircles.codehaus.org/projects/fabric3/lists+. There are several mailing lists for Fabric3. Please post questions to the user list. The developer list is intended for topics related to ongoing Fabric3 development and is not a general forum for questions. However, if you are interested in Fabric3 development, we encourage you to participate in discussions.
Should you encounter a bug, we encourage you to file a report in the online JIRA system at {+}http://jira.codehaus.org/browse/FABRICTHREE+. If possible, please include a detailed description and failing testcase (or other appropriate means) to reproduce the problem. Assisting Fabric3 developers in reproducing the problem generally leads to faster resolution.