Java Platform, Enterprise Edition (Java EE) 8 The Java EE Tutorial

## Resource Library Contracts

Resource library contracts allow you to define a different look and feel for different parts of one or more applications, instead of either having to use the same look and feel for all or having to specify a different look on a page-by-page basis.

To do this, you create a `contracts` section of your web application. Within the `contracts` section, you can specify any number of named areas, each of which is called a contract. Within each contract you can specify resources such as template files, stylesheets, JavaScript files, and images.

For example, you could specify two contracts named `c1` and `c2`, each of which uses a template and other files:

    src/main/webapp
        WEB-INF/
        contracts
            c1
                template.xhtml
                style.css
                myImg.gif
                myJS.js
            c2
                template.xhtml
                style2.css
                img2.gif
                JS2.js
        index.xhtml
        ...

One part of the application can use `c1`, while another can use `c2`.

Another way to use contracts is to specify a single contract that contains multiple templates:

    src/main/webapp
        contracts
            myContract
                template1.xhtml
                template2.xhtml
                style.css
                img.png
                img2.png

You can package a resource library contract in a JAR file for reuse in different applications. If you do so, the contracts must be located under `META-INF/contracts`. You can then place the JAR file in the `WEB-INF/lib` directory of an application. This means that the application would be organized as follows:

    src/main/webapp/
        WEB-INF/lib/myContract.jar
        ...

You can specify the contract usage within an application’s `faces-config.xml` file, under the `resource-library-contracts` element. You need to use this element only if your application uses more than one contract, however.

### The hello1-rlc Example Application

The `hello1-rlc` example modifies the simple `hello1` example from A Web Module That Uses JavaServer Faces Technology: The hello1 Example to use two resource library contracts. Each of the two pages in the application uses a different contract.

The managed bean for `hello1-rlc`, `Hello.java`, is identical to the one for `hello1` (except that it replaces the `@Named` and `@RequestScoped` annotations with `@Model`).

The source code for this application is in the tut-install`/examples/web/jsf/hello1-rlc/` directory.

The following topics are addressed here:

- Configuring the hello1-rlc Example

- The Facelets Pages for the hello1-rlc Example

- To Build, Package, and Deploy the hello1-rlc Example Using NetBeans IDE

- To Build, Package, and Deploy the hello1-rlc Example Using Maven

- To Run the hello1-rlc Example

#### Configuring the hello1-rlc Example

The `faces-config.xml` file for the `hello1-rlc` example contains the following elements:

    <resource-library-contracts>
        <contract-mapping>
            <url-pattern>/reply/*</url-pattern>
            <contracts>reply</contracts>
        </contract-mapping>
        <contract-mapping>
            <url-pattern>*</url-pattern>
            <contracts>hello</contracts>
        </contract-mapping>
    </resource-library-contracts>

The `contract-mapping` elements within the `resource-library-contracts` element map each contract to a different set of pages within the application. One contract, named `reply`, is used for all pages under the `reply` area of the application (`/reply/*`). The other contract, `hello`, is used for all other pages in the application (`*`).

The application is organized as follows:

    hello1-rlc
        pom.xml
        src/main/java/javaeetutorial/hello1rlc/Hello.java
        src/main/webapp
            WEB-INF
                faces-config.xml
                web.xml
            contracts
                hello
                    default.css
                    duke.handsOnHips.gif
                    template.xhtml
                reply
                    default.css
                    duke.thumbsup.gif
                    template.xhtml
            reply
                response.xhtml
            greeting.xhtml

The `web.xml` file specifies the `welcome-file` as `greeting.xhtml`. Because it is not located under `src/main/webapp/reply`, this Facelets page uses the `hello` contract, whereas `src/main/webapp/reply/response.xhtml` uses the `reply` contract.

#### The Facelets Pages for the hello1-rlc Example

The `greeting.xhtml` and `response.xhtml` pages have identical code calling in their templates:

    <ui:composition template="/template.xhtml">

The `template.xhtml` files in the `hello` and `reply` contracts differ only in two respects: the placeholder text for the `title` element ("Hello Template" and "Reply Template") and the graphic that each specifies.

The `default.css` stylesheets in the two contracts differ in only one respect: the background color specified for the `body` element.

#### To Build, Package, and Deploy the hello1-rlc Example Using NetBeans IDE

1. Make sure that GlassFish Server has been started (see Starting and Stopping GlassFish Server).

2. From the File menu, choose Open Project.

3. In the Open Project dialog box, navigate to:

       tut-install/examples/web/jsf

4. Select the `hello1-rlc` folder.

5. Click Open Project.

6. In the Projects tab, right-click the `hello1-rlc` project and select Build.

   This option builds the example application and deploys it to your GlassFish Server instance.

#### To Build, Package, and Deploy the hello1-rlc Example Using Maven

1. Make sure that GlassFish Server has been started (see Starting and Stopping GlassFish Server).

2. In a terminal window, go to:

       tut-install/examples/web/jsf/hello1-rlc/

3. Enter the following command:

       mvn install

   This command builds and packages the application into a WAR file, `hello1-rlc.war`, that is located in the `target` directory. It then deploys it to your GlassFish Server instance.

#### To Run the hello1-rlc Example

1. Enter the following URL in your web browser:

       http://localhost:8080/hello1-rlc

2. The `greeting.xhtml` page looks just like the one from `hello1` except for its background color and graphic.

3. In the text field, enter your name and click Submit.

4. The response page also looks just like the one from `hello1` except for its background color and graphic.

   The page displays the name you submitted. Click Back to return to the `greeting.xhtml` page.

Copyright © 2017, Oracle and/or its affiliates. All rights reserved.