Introduction

Fabric3 is a platform for developing, assembling, and managing distributed applications. Fabric3 provides the following features:

• A programming model based on Service Component Architecture (SCA) that is specifically designed for building and integrating loosely-coupled systems.

• The ability to use a variety of remote communication protocols in a unified, consistent manner without tying application logic to specific transport APIs.

• A cross-application policy framework for implementing and enforcing policies such as security and SLAs throughout an organization.

• A management framework for provisioning, controlling, and monitoring production deployments.

• Portability across a variety of middleware environments including Tomcat, and WebLogic.

In this chapter, we cover the basics of setting up and deploying an application using Fabric3. 

The documentation assumes a basic understanding of SCA concepts. Before proceeding, if you have not done so, we recommend familiarizing yourself with SCA. The specifications themselves (http://www.oasis-opencsa.org) are generally not the most accessible source of introductory information. We recommend:

• David Chappell, "Introducing SCA" (http://www.davidchappell.com/articles/Introducing_SCA.pdf), which presents a balanced and accurate overview of SCA.

• Jim Marino and Michael Rowley, Understanding SCA (Addison-Wesley), which provides an in-depth treatment of SCA using Fabric3. 

The Samples

The Fabric3 samples are organized as follows:

• Starter: Contains several variations of a calculator application that show how to create services, wire them, and expose them as a web services endpoint and REST resource.

• Features: Contains applications that demonstrate how to use specific Fabric3 features, including JPA/Hibernate, pub/sub eventing, websockets, timers, and custom policies.

• Apps. Contains complete applications that demonstrate SCA and Fabric3 best-practices. There is currently one application, BigBank.

• Operations. Contains samples that demonstrate how to use Fabric3's REST-based management API (Resource Management Framework) to monitor, control, and update single-VM to multi-cluster domains.

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.

Prerequisites

The samples may be downloaded from http://www.fabric3.org/downloads and require the following software:

• JDK 6.0 or later.
• Maven 2.2.8 or later. Maven can be downloaded from http://maven.apache.org/download.html.

The Starter Applications

The starter calculator applications are the recommended way to get familiar with Fabric3. To build and deploy the calculator applications, do the following:

Build the starter modules.

In the directory where you extracted the samples distribution, go to the /starter project folder and execute: mvn clean install JARs containing the application artifacts will be created in the /target output directories for each application.

Build the Fabric3 server distribution.

Download the Fabric3 runtime by executing the Maven build script from the 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.

Start the server.

To launch a Fabric3 server in single-VM mode, execute the following from the servers/vm/target/image/bin directory: 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



Deploy the application

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 archive has been deployed. Depending on the application deployed, one of the following endpoints will be available:

• The web calculator UI can be accessed at http://localhost:8181/ calculator/entry.html.
• The REST calculator resource can be accessed using a GET with the formula to calculate included in the URI as in: http://localhost:8181/calculator/1+1.
• The web services calculator can be accessed at 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.

Feature Applications

Feature applications provide in-depth examples of how to use a particular Fabric3 feature, such as pub/sub eventing. As with the starter applications, a feature application can be built and deployed to one of the server configurations.

The Monitor Sample

This sample demonstrates sending monitor events to a custom channel. The channel is bound to a Websocket address, allowing monitor events to be pushed to a browser using JQuery. After deploying the application, point a browser to http://localhost:8181/monitor/monitor.html to receive events. Every fifth event is an error event displayed in red.

BigBank

BigBank demonstrates a complete distributed, multi-cluster loan processing application. BigBank is organized into several architectural tiers:

• A loan service tier responsible for providing a RESTful and WS-* web service that receives loan applications.
• A back-end services tier responsible for performing credit checks, rating, pricing, and managing approvals.
• A consumer web-based UI for submitting new applications and reviewing loan status.
• A back-office web-based UI for managing loan approvals and viewing real-time business events and statistics.  
• A database tier for persisting loan application data.

BigBank can be deployed to the single-VM runtime used for the starter examples or deployed to the two-cluster topology that is configured under servers/cluster. In either case, configuration remains the same. When deployed to the cluster environment, the loan service and web UIs will be deployed to the cluster zone1 while the back-end services will be deployed to the cluster zone2. Fabric3 will wire the services by transparently provisioning a number of JMS queues and topics. 

Deploying to a Single VM

To build and deploy BigBank to the single-VM server, do the following:

Build the BigBank source. 

To build BigBank, go to apps/bigbank and execute: mvn clean install
.

The build will produce three archives: the loan application and back-end services contribution (bigbank-loan-<version>.jar); the consumer UI (bigbank-web-<version>.war); and the back-office UI (bigbank-backoffice-<version>.war). 

Start the server.

Boot the Fabric3 runtime from the server/vm/image/bin directory by executing: java -jar server.jar



Deploy the archives.

Copy bigbank-loan-<version>.jar to the severs/vm/target/image/runtimes/vm/deploy directory. Next, copy the two war archives to the deploy directory.

Deploying to a Distributed Domain

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:

• Launch the shared H2 database process from cluster/database: java -jar target/h2-1.2.140.jar 
  * From the controller/target/image/bin directory: java -jar server.jar controller
 
  * From the zone1/target/image/bin directory: java -jar server.jar participant
 
  * From the zone2/target/image/bin directory: java -jar server.jar participant 


After booting, the runtimes will discover each other and form a distributed domain consisting of two clusters (zones). Note the runtimes may be on the same machine or different machines. Copy the BigBank archives to the controller/target/image/runtimes/controller/deploy directory. The controller will provision the loan service and web UIs to zone1 and the backend services to zone2.

Getting Help

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.