type=page
status=published
title=The encoder Example: Using Alternatives
next=cdi-adv-examples003.html
prev=cdi-adv-examples001.html
~~~~~~
= The encoder Example: Using Alternatives


[[GKHPU]]

[[the-encoder-example-using-alternatives]]
The encoder Example: Using Alternatives
---------------------------------------

The `encoder` example shows how to use alternatives to choose between
two beans at deployment time, as described in
link:cdi-adv002.html#GJSDF[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.

The following topics are addressed here:

* link:#GKHQA[The Coder Interface and Implementations]
* link:#GKHPM[The encoder Facelets Page and Managed Bean]
* link:#GKHQQ[Running the encoder Example]

[[GKHQA]]

[[the-coder-interface-and-implementations]]
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.

[source,oac_no_warn]
----
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`:

[source,oac_no_warn]
----
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:

[source,oac_no_warn]
----
<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.

[[GKHPM]]

[[the-encoder-facelets-page-and-managed-bean]]
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`:

[source,oac_no_warn]
----
<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:

[source,oac_no_warn]
----
@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:

[source,oac_no_warn]
----
    public void encodeString() {
        setCodedString(coder.codeString(inputString, transVal));
    }
----

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

[source,oac_no_warn]
----
    public void reset() {
        setInputString("");
        setTransVal(0);
    }
----

[[GKHQQ]]

[[running-the-encoder-example]]
Running the encoder Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

[[GKHOW]]

[[to-build-package-and-deploy-the-encoder-example-using-netbeans-ide]]
To Build, Package, and Deploy the encoder Example Using NetBeans IDE
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1.  Make sure that GlassFish Server has been started (see
link:usingexamples002.html#BNADI[Starting and Stopping GlassFish
Server]).
2.  From the File menu, choose Open Project.
3.  In the Open Project dialog box, navigate to:
+
[source,oac_no_warn]
----
tut-install/examples/cdi
----
4.  Select the `encoder` folder.
5.  Click Open Project.
6.  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.

[[GKHQU]]

[[to-run-the-encoder-example-using-netbeans-ide]]
To Run the encoder Example Using NetBeans IDE
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1.  In a web browser, enter the following URL:
+
[source,oac_no_warn]
----
http://localhost:8080/encoder
----
2.  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`.
3.  Now, edit the `beans.xml` file to enable the alternative
implementation of `Coder`.
a.  In the Projects tab, under the `encoder` project, expand the Web
Pages node, then expand the WEB-INF node.
b.  Double-click the `beans.xml` file to open it.
c.  Remove the comment characters that surround the `alternatives`
element, so that it looks like this:
+
[source,oac_no_warn]
----
<alternatives>
    <class>javaeetutorial.encoder.TestCoderImpl</class>
</alternatives>
----
d.  Save the file.
4.  Right-click the `encoder` project and select Clean and Build.
5.  In the web browser, reenter the URL to show the String Encoder page
for the redeployed project:
+
[source,oac_no_warn]
----
http://localhost:8080/encoder/
----
6.  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:
+
[source,oac_no_warn]
----
Result: input string is Java, shift value is 4
----

[[GKHQL]]

[[to-build-package-and-deploy-the-encoder-example-using-maven]]
To Build, Package, and Deploy the encoder Example Using Maven
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1.  Make sure that GlassFish Server has been started (see
link:usingexamples002.html#BNADI[Starting and Stopping GlassFish
Server]).
2.  In a terminal window, go to:
+
[source,oac_no_warn]
----
tut-install/examples/cdi/encoder/
----
3.  Enter the following command to deploy the application:
+
[source,oac_no_warn]
----
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.

[[GKHOL]]

[[to-run-the-encoder-example-using-maven]]
To Run the encoder Example Using Maven
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1.  In a web browser, enter the following URL:
+
[source,oac_no_warn]
----
http://localhost:8080/encoder/
----
+
The String Encoder page opens.
2.  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`.
3.  Now, edit the `beans.xml` file to enable the alternative
implementation of `Coder`.
a.  In a text editor, open the following file:
+
[source,oac_no_warn]
----
tut-install/examples/cdi/encoder/src/main/webapp/WEB-INF/beans.xml
----
b.  Remove the comment characters that surround the `alternatives`
element, so that it looks like this:
+
[source,oac_no_warn]
----
<alternatives>
    <class>javaeetutorial.encoder.TestCoderImpl</class>
</alternatives>
----
c.  Save and close the file.
4.  Enter the following command:
+
[source,oac_no_warn]
----
mvn clean install
----
5.  In the web browser, reenter the URL to show the String Encoder page
for the redeployed project:
+
[source,oac_no_warn]
----
http://localhost:8080/encoder
----
6.  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:
+
[source,oac_no_warn]
----
Result: input string is Java, shift value is 4
----
