The Java EE 7 Tutorial

26.1 The encoder Example: Using Alternatives

The encoder example shows how to use alternatives to choose between two beans at deployment time, as described in Using Alternatives in CDI Applications. The example includes an interface and two implementations of it, a managed bean, a Facelets page, and configuration files.

The source files are located in the tut-install/examples/cdi/encoder/src/main/java/javaeetutorial/encoder/ directory.

26.1.1 The Coder Interface and Implementations

The Coder interface contains just one method, codeString, that takes two arguments: a string, and an integer value that specifies how the letters in the string should be transposed.

public interface Coder {

    public String codeString(String s, int tval);
}

The interface has two implementation classes, CoderImpl and TestCoderImpl. The implementation of codeString in CoderImpl shifts the string argument forward in the alphabet by the number of letters specified in the second argument; any characters that are not letters are left unchanged. (This simple shift code is known as a Caesar cipher because Julius Caesar reportedly used it to communicate with his generals.) The implementation in TestCoderImpl merely displays the values of the arguments. The TestCoderImpl implementation is annotated @Alternative:

import javax.enterprise.inject.Alternative;

@Alternative
public class TestCoderImpl implements Coder {

    @Override
    public String codeString(String s, int tval) {
        return ("input string is " + s + ", shift value is " + tval);
    }
}

The beans.xml file for the encoder example contains an alternatives element for the TestCoderImpl class, but by default the element is commented out:

<beans ...>
    <!--<alternatives>
        <class>javaeetutorial.encoder.TestCoderImpl</class>
    </alternatives>-->
</beans>

This means that by default, the TestCoderImpl class, annotated @Alternative, will not be used. Instead, the CoderImpl class will be used.

26.1.2 The encoder Facelets Page and Managed Bean

The simple Facelets page for the encoder example, index.xhtml, asks the user to enter the string and integer values and passes them to the managed bean, CoderBean, as coderBean.inputString and coderBean.transVal:

<html lang="en"
      xmlns="http://www.w3.org/1999/xhtml"
      xmlns:h="http://java.sun.com/jsf/html">
    <h:head>
        <h:outputStylesheet library="css" name="default.css"/>
        <title>String Encoder</title>
    </h:head>
    <h:body>
        <h2>String Encoder</h2>
        <p>Type a string and an integer, then click Encode.</p>
        <p>Depending on which alternative is enabled, the coder bean
            will either display the argument values or return a string that
            shifts the letters in the original string by the value you
            specify. The value must be between 0 and 26.</p>
        <h:form id="encodeit">
            <p><h:outputLabel value="Enter a string: " for="inputString"/>
                <h:inputText id="inputString"
                             value="#{coderBean.inputString}"/>
                <h:outputLabel value="Enter the number of letters to shift by: "
                               for="transVal"/>
                <h:inputText id="transVal" value="#{coderBean.transVal}"/></p>
            <p><h:commandButton value="Encode"
                                action="#{coderBean.encodeString()}"/></p>
            <p><h:outputLabel value="Result: " for="outputString"/>
                <h:outputText id="outputString"
                              value="#{coderBean.codedString}"
                              style="color:blue"/></p>
            <p><h:commandButton value="Reset"
                                action="#{coderBean.reset}"/></p>
        </h:form>
        ...
    </h:body>
</html>

When the user clicks the Encode button, the page invokes the managed bean's encodeString method and displays the result, coderBean.codedString, in blue. The page also has a Reset button that clears the fields.

The managed bean, CoderBean, is a @RequestScoped bean that declares its input and output properties. The transVal property has three Bean Validation constraints that enforce limits on the integer value, so that if the user enters an invalid value, a default error message appears on the Facelets page. The bean also injects an instance of the Coder interface:

@Named
@RequestScoped
public class CoderBean {

    private String inputString;
    private String codedString;
    @Max(26)
    @Min(0)
    @NotNull
    private int transVal;

    @Inject
    Coder coder;
    ...

In addition to simple getter and setter methods for the three properties, the bean defines the encodeString action method called by the Facelets page. This method sets the codedString property to the value returned by a call to the codeString method of the Coder implementation:

    public void encodeString() {
        setCodedString(coder.codeString(inputString, transVal));
    }

Finally, the bean defines the reset method to empty the fields of the Facelets page:

    public void reset() {
        setInputString("");
        setTransVal(0);
    }

26.1.3 Running the encoder Example

You can use either NetBeans IDE or Maven to build, package, deploy, and run the encoder application.

26.1.3.1 To Build, Package, and Deploy the encoder Example Using NetBeans IDE

Make sure that GlassFish Server has been started (see Starting and Stopping GlassFish Server).
From the File menu, choose Open Project.
In the Open Project dialog box, navigate to:
```
tut-install/examples/cdi
```
Select the encoder folder.
Click Open Project.
In the Projects tab, right-click the encoder project and select Build.

This command builds and packages the application into a WAR file, encoder.war, located in the target directory, and then deploys it to GlassFish Server.

26.1.3.2 To Run the encoder Example Using NetBeans IDE

In a web browser, enter the following URL:
```
http://localhost:8080/encoder
```
On the String Encoder page, enter a string and the number of letters to shift by, and then click Encode.

The encoded string appears in blue on the Result line. For example, if you enter Java and 4, the result is Neze.
Now, edit the beans.xml file to enable the alternative implementation of Coder.
1. In the Projects tab, under the encoder project, expand the Web Pages node, then expand the WEB-INF node.
2. Double-click the beans.xml file to open it.
3. Remove the comment characters that surround the alternatives element, so that it looks like this:
```
<alternatives>
    <class>javaeetutorial.encoder.TestCoderImpl</class>
</alternatives>
```
4. Save the file.
Right-click the encoder project and select Clean and Build.
In the web browser, reenter the URL to show the String Encoder page for the redeployed project:
```
http://localhost:8080/encoder/
```
Enter a string and the number of letters to shift by, and then click Encode.

This time, the Result line displays your arguments. For example, if you enter Java and 4, the result is:
```
Result: input string is Java, shift value is 4
```

26.1.3.3 To Build, Package, and Deploy the encoder Example Using Maven

Make sure that GlassFish Server has been started (see Starting and Stopping GlassFish Server).
In a terminal window, go to:
```
tut-install/examples/cdi/encoder/
```
Enter the following command to deploy the application:
```
mvn install
```
This command builds and packages the application into a WAR file, encoder.war, located in the target directory, and then deploys it to GlassFish Server.

26.1.3.4 To Run the encoder Example Using Maven

In a web browser, enter the following URL:
```
http://localhost:8080/encoder/
```
The String Encoder page opens.
Enter a string and the number of letters to shift by, and then click Encode.

The encoded string appears in blue on the Result line. For example, if you enter Java and 4, the result is Neze.
Now, edit the beans.xml file to enable the alternative implementation of Coder.
1. In a text editor, open the following file:
```
tut-install/examples/cdi/encoder/src/main/webapp/WEB-INF/beans.xml
```
2. Remove the comment characters that surround the alternatives element, so that it looks like this:
```
<alternatives>
    <class>javaeetutorial.encoder.TestCoderImpl</class>
</alternatives>
```
3. Save and close the file.
Enter the following command:
```
mvn clean install
```
In the web browser, reenter the URL to show the String Encoder page for the redeployed project:
```
http://localhost:8080/encoder
```
Enter a string and the number of letters to shift by, and then click Encode.

This time, the Result line displays your arguments. For example, if you enter Java and 4, the result is:
```
Result: input string is Java, shift value is 4
```

Release: Java EE 7.0