Frequently Asked Questions about Mojarra (Sun's JSF implementation)

This Wiki page is for questions about Mojarra (Sun's JSF implementation). General FAQs about the JSF Specification are covered in The FAQ for the JSF Specification.

Table of Contents:

Working with the source code

How do I access the source tree via CVS?

Access to the source code for Sun's implementation of the JCP JSF Specification is subject to the terms of either the GNU General Public License Version 2 only ("GPL") or the Common Development and Distribution License("CDDL") (collectively, the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the License at here.

Refer to the version control instructions for details on configuring your client.

If you don't have a java.net ID, you can check out the source anonymously by using the guest account.

The version control instructions also contains information pertaining to branch names which will be important depending on which version of JSF you're interested in working with.

What are the tags for the current releases of Mojarra?

• Mojarra 1.2_10 -> JSF_1_2_10_B01 (cvs)
• Mojarra 1.2_11 -> JSF_1_2_11_B01 (cvs)
• Mojarra 2.0 PR -> 2_0_0_B08 (svn)

Do I need to download any dependencies before I attempt to build the source?

No, though we don't use Maven, we do have a system in place to download all the necessary dependencies you will need in order to build and test the implementation.

How do I build the Mojarra sources?

Assuming SOURCE_HOME is the directory containing the javaserverfaces-sources...

1. Copy build.properties.glassfish to build.properties
2. Edit build.properties and set jsf.build.home to SOURCE_HOME
3. From SOURCE_HOME run ant clean main - this will build the API as well as the implementation

The jsf-api.jar will be in SOURCE_HOME/jsf-api/build/lib and jsf-impl.jar will be in SOURCE_HOME/jsf-ri/build/lib.

How do I run the unit tests?

There are two major sets of tests in the source tree. One set for the API, and the other set for the implementation. All of them can be run by invoking a single ant command from the root source directory: ant test.with.container.refresh. This target will cause the JSF API and implementation to be deployed to the GlassFish server that is downloaded as part of the build process and run the tests after the server has finished starting up.

How can I contribute?

Please note the following:

• Your feedback is valuable to us, so join our mailing lists and give input.
• Bug reports are very helpful to developers and a great way to contribute to the project. Use the issue tracker to report a bug. Please be sure to include as much information with your report as possible such as a test case, your platform, version number and steps to reproduce the problem.
• If you like to propose a new feature, file an enhancement issue for it.
• You are welcome to submit a patch for a feature you'd like to see or a bug you'd like to get fixed. All contributers must complete the Joint Copyright Assignment form before contributions can be included in the project. Print, complete, sign and mail or fax the Joint Copyright Assignment form to:

Eric Renaud JSF/Sun Microsystems 4120 Network Circle, USCA 12-105 Santa Clara, CA 95054 USA Fax: 1-408-715-2540

Or, send a scanned version to JSF_JCA_submit@sun.com.

For more information on the SCA, see the FAQ.

Follow the instructions in How do I prepare a change bundle? for quick acceptance of your patch. If your patch doesn't include a test case, we would have to create or update an existing test for it which would delay the acceptance of your patch. If you are unable to do so, you can do the following:

The developer responsible for the section of code affected should either apply the patch and mark the issue FIXED; or add a comment with an objection if the patch does not seem safe, does not appear to fix the problem, or there is not really a problem to begin with. Developers must also confirm that the contributor has filled in and submitted a JCA before commiting their patch.

Notifications of any changes to Issue Tracking, as well as CVS checkins, are automatically sent to the appropriate bug and CVS mailing lists, so you can monitor if the patch has really been applied. Make sure you subscribe to at least the CVS and bug mailing lists for the module you are working on - see the mailing lists page for details.

How do I prepare a change bundle?

The JavaServer Faces team practices Test First Design. All code checked in must be accompanied by a new automated testcase that exercises that code, or changes to an existing automated testcase that exercises the code. When writing your code, you have the choice of whether a unit test or a system test would be more appropriate to verify the correctness of your code. Unit tests live in the jsf-ri/test directory, and system tests live in the jsf-ri/systest directory.

Please read this article, other literature, or contact project owner for an introduction to Test First Design.

• As a general note, please turn off any auto-formatting in your IDE to keep your diffs to a minimum. Encountering lots of semantically meaningless changes in the version history of a file, mixed in with semantically meaningfull ones, is very confusing. If you must make formatting changes, do so in a separate change-bundle.
  

BEFORE CHECKIN, each significant code change to the repository is described in a "change bundle" and sent to dev@javaserverfaces.dev.java.net for review by module owners. If the change-bundle is to fix a bug, the change-bundle can be posted to the bug (either as an attachment or a comment) and a pointer to the bug can be sent to dev@javaserverfaces.dev.java.net.

The change bundle should be sent in a way that is easiest for the reviewer to review. Examples of change-bundles can be found here.

For your convenience, you can simply run the command ant cb to generate the change bundle for you. Please refer to the issue "id" in the bundle and in the subject of your email.

• The module owner reviews the change bundle
  • If the reviewer gives approval, you can check it in as is. Please follow the checkin process. Approval is signified by the reviewer replying to the change bundle mail with r=userid.
    

For example: Looks good, r=edburns

• • If the reviewer requests revisions, you need to produce another change bundle and seek approval. Repeat until approval is given.

What is the code checkin procedure?

Once you have completed the review process, please follow this process to ensure a smooth checkin that doesn't break the tree.

• cd to the top level of your workarea. Make sure everything still compiles and runs. This means you do the following on jsf-api as well as on jsf-ri. This will run all the unit tests on jsf-api and run all the unit tests and systest on jsf-ri.
  • ant
  • ant test on jsf-api/ and ant test on jsf-ri/

• If the checkin contains non-documentation files, you cannot checkin until both the "ant" and the "ant test" commands have run successfully on your machine.
• Make sure jsf-guessNumber, jsf-cardemo, jsf-components demos run successfully.
• Run ant test on the jsf-demo/// directory. This will run the HTMLUnit automated tests on the demos.
• Once you have run all the tests successfully, you are ready to commit. Run this command
  

cvs -n update -d -P

• Examine the output. Most importantly, make sure that every file marked with a ? is not intended for check in. Doing this check ensures that your complete set of files will be checked in without omissions. If there are files marked with a ? that are intended for check in, cvs add them and go back to the beginning of this Process.
  
  

If there are any files marked with a P or a U, you must update your tree before checking in. Do a top level

cvs update -d -P

and go to the top of this process.

• Use the output from the previous step as the basis for your checkin message. Make sure you describe what has changed in each modified or added file.
• It's time to commit. At this point you're certain that your workarea is completely up to date, all files intended for checkin are marked for checkin, and everything compiles and works. Try to issue the cvs commit command from the lowest possible directory that is a parent of all the directories in which the files have been changed or added. If you can avoid doing a toplevel commit, then please do so. Run the command
  

cvs commit

Type in your log message, or import it from a message file via cut and past or some such.

How do I become a committer?

Follow How can I contribute? and start contributing enough [#HowToBundle]solid patches] that get accepted into the codebase so that we can get a feel for the quality of your code. Contributors who give frequent and valuable contributions will be nominated for "developer" role if they desire. We would appreciate if commiters could abide by the code review and test driven development process we use.

If you think this process is too onerous, please send your comments to project owner.

Questions pertaining only to Sun's implementation of the JSF 1.2 specification

How can I turn on logging?

• Learn which logger you want to turn on. If you look in com.sun.faces.util.Util you find some useful constants for logging. It lists every logger:

FACES_LOGGER=javax.enterprise.resource.webcontainer.jsf

Other logger constants are:

APPLICATION_LOGGER = ".application"
CONFIG_LOGGER = ".config"
CONTEXT_LOGGER = ".context"
LIFECYCLE_LOGGER = ".lifecycle"
MANAGEDBEAN_LOGGER = ".managedbean" (added in 1.2_05)
RENDERKIT_LOGGER = ".renderkit"
TAGLIB_LOGGER = ".taglib"
TIMING_LOGGER = ".timing"

If you want to turn on only the logger for render kit, for exmple, the logger is javax.enterprise.resource.webcontainer.jsf.renderkit.

• If using Glassfish V2
  • Going on with the intent of turning on the logger for render kit, make a logging config file, for example "jsf-log-config", containing only this line:
    

javax.enterprise.resource.webcontainer.jsf.renderkit.level=FINEST

• • Edit your domain.xml file:
    

Look for a <java-config> element, and add there a <jvm-options>. If you have put the "jsf-log-config" file in "domains/domain1/config/", for example, your jvm-options looks like this:

<jvm-options>-Djava.util.logging.config.file=${com.sun.aas.instanceRoot}/config/jsf-log-config</jvm-options>

• If using Glassfish V3 prelude or later, rather than creating a separate file and
  

domain.xml to point to it, modify the "logging.properties" file, which is in the same
directory as the domain.xml file. Place entries in the logging.properties file as you
would place them in the log-config file from the Glassfish V2 instructions.

• Run the appserver. The messages will appear in the regular application server log.

What is required to build JSF 1.2.x?

• GlassFish or any JSP2.1/J2EE 5.0 based container
• J2SE 5.0 or later

How do I build the code?

Make sure you have installed everything outlined in What is required to build JSF 1.1.x and JSF 1.2.x? and What is required to build JSF 1.2.x?. Make it so JDK and Ant are runnable from the command line. This involves setting up the environment per the Ant instructions.

Steps

• If you are planning on running the unit tests, copy $JUNIT_HOME/junit.jar to your $ANT_HOME/lib directory.
• Change directory to the location of the checked out source.
• Copy build.properties.glassfish to build.properties and set the following properties:
  
  • jsf.build.home - this must be set to the same directory of the checked out source
  • container.home - this is the base directory of your GlassFish installation. This property defaults to ${jsf.build.home}/dependencies/glassfish. Only override it if you wish to point to a different GlassFish installation (for testing purposes).
  • glassfish.password.file - this specifies the file containing the GlassFish administrative password. The property file details the contents of this file. This defaults to ${jsf.build.home}/dependencies/glassfish/password.txt. The password in this file is the default of 'adminadmin'. Override this propery if you have a custom password for your GlassFish instance.

There are various other properties that can be toggled to modify the build/test behavior. Review the property file for details on the different properties.

• Run _ant_. This will download the necessary dependencies and build the jsf-api and jsf-impl JARs. The jsf-api.jar will be located under jsf-api/build/lib and jsf-impl.jar will be located under jsf-ri/build/lib.
• In order for GlassFish to take advantage of any changes you may make, run the _container.deploy_ target (this can be run from _jsf.build.home_ or any subdirectory therein. This target will update the appropriate GlassFish artifacts. If you are using some other container, this target could still be used, but confirm with the container's docs. If you are not building from source but just want to override the JSF JARs in GlassFish, do the following:
  
  
  • Restart the server for the updates to take effect.
  • To build and deploy the JSF sample applications, change directory to jsf-demo directory. Run _ant_. This will build all the demos that ship with the JSF distribution namely guessNumber, cardemo, component and nonjsp.
  • To deploy the application to GlassFish, you have two options. You can copy the war file to container's _autodeploy_ directory which is under (GLASSFISH.HOME/domains/domain1/autodeploy) or you can use the asadmin utility to deploy the war file.

How do I run the automated unit and system tests using Glassfish?

Get to the point where you can build the code by following the above steps. Set the required properties in build.properties.

• On the Mac OS X 10.4 Platform, you need to copy $JAVA_HOME/lib/ext/sunjce_provider.jar to glassfish.home/lib.
• To run all tests, run _ant test.with.container.refresh_
• To run the API tests, run _ant test_ from jsf-api. This will run all API tests.
• To run the RI tests:
  • If you have GlassFish running, stop the server. Run _ant config.container_. This performs the necessary configuration modifications. Restart the server.
  • Stop Glassfish, if it's currently running. Run _ant container.deploy_ from the top directory. Restart Glassfish.
  • Run _ant test_ from jsf-ri. This will run all unit tests.
• For your information: There are four separate suites of tests run when _ant test_ is invoked from jsf-ri and can be invoked using the following targets:
  • run.junit.test -> runs a small suite of standalone tests that do not require the container
  • run.cactus.test -> runs the cactus-based tests
  • run.systest -> runs the system tests (basically end-to-end tests simulating http clients)
  • run.systest-per-webapp -> similar to the systests above, but these tests are run in separate web applications to keep the environment clean.

If you encounter any problems running the unit tests, ensure that the target _config.container_ was invoked. If the command was invoked, verify the following settings exist glassfish.home/domains/domain1/config/server.policy.

• java.util.PropertyPermission set to "read,write" (not just "read")
• permission java.lang.reflect.ReflectPermission "*";

Also, ensure the keepalive timeout is set to 70 seconds in glassfish.home/domains/domain1/config/domain.xml (search for keep-alive). These changes are necessary because some of the unit tests access system properties and access package private variables from jsf-impl in order to test some functionality. The keepalive change is necessary as one of the tests sleeps for a minute before continuing. Without this change, the test would fail due to the connection being reset.

How do I debug a JSF Application using Glassfish/NetBeans 4.1?

• Start Glassfish in debug mode. To do this, edit GlassFish.home/domains/domain1/config/domain.xml. Look for java-config element. Set "debug-enabled" to "true". Restart the server.
• Attach NetBeans debugger. Use the following values for Attach and click on "OK".
  • Debugger: JDPA Debugger
  • Connector: SocketAttach
  • Transport: dt_socket
  • Host: _your host name_
  • Port: 9009 (If you modified domain.xml to use a different port, use that port number)

Now, when you deploy and run your JSF application, you should see the debuuger stop at your break points.

How do I update the JSF implementation in the Java EE SDK (or glassfish) with the most recent version?

The JSF Team has a new, experimental, download offering in its Documents and Files section that will overlay the latest JSF nightly onto a given glassfish install directory. Please visit the nightly build section of the JSF Documents and Files project and download the jsf-glassfish-updater.jar. This file contains the latest JSF nightly and can be executed as follows to install it into glassfish.

java -jar jsf-glassfish-updater.jar /PATH/TO/YOUR/GLASSFISH/INSTALL/DIRECTORY

Where /PATH/TO/YOUR/GLASSFISH/INSTALL/DIRECTORY is the parent of the lib/, bin/, domains/ (and so on) directories.

The jsf-glassfish-updater.jar file will be updated nightly with the latest JSF nightly build, and is a great way to get the latest JSF in cases where there is no available Glassfish build with the bug-fix you need, or you just don't want to download a whole new Glassfish.

What context parameters are available and what do they do?

The following context parameters are supported the reference implementation and are specific to that implementation. Thanks to Adrian Mitev for compiling this table.

I see this error: JSF1033: Resource injection is DISABLED

This is not necessary if you're using a milestone build of GlassFish UR1 or GlassFish V2. Edit your APPSERV_HOME/domains//config/default-web.xml and add the following context init parameter:

• Param Name: com.sun.faces.injectionProvider -- Param Value: com.sun.faces.vendor.GlassFishInjectionProvider

<context-param>
<param-name>com.sun.faces.injectionProvider</param-name>
<param-value>com.sun.faces.vendor.GlassFishInjectionProvider</param-value>
</context-param>

• Restart the modified domain.

I receive an IllegalStateException when restoring a view that uses anonymous classes for items such as Listeners

This isn't a bug in JSF state saving. In fact, serialization of anonymous class instances is discouraged due to several known complications. These are spelled out in section 1.10 of the serialization specification.

This has been raised as an issue with the JVM team, but closed as NOT A BUG. Please see bug 4862448 for further details.

My container doesn't support ServletContextListeners defined in TLDs, what listeners are used by the Mojarra?

• com.sun.faces.config.ConfigureListener (used to parse configuration resources and bootstrap the application)
• com.sun.faces.application.WebappLifecycleListener (used by resource injection)
• com.sun.faces.util.ReflectionUtils$ReflectionUtilsListener (used to init and clear reflection caches)

As of 1.2_05, there is only one listener - com.sun.faces.config.ConfigureListener.

General JSF-related questions

How do I write a JSF component?

Component writing can be, at least at first, an almost overwhelming task. To make things a bit simpler, Mojarra committer Jason Lee has written a quick check list of things to do when writing components, with special attention paid to those areas where the 1.1 and 1.2 specs differ.

Can I download the Mojarra jars from a Maven repository?

Both the 1.1 and 1.2 versions of the Mojarra are available from java.net's Maven repository.

I'm trying to deploy to a non-EE server. Where do I find the EL jars?

The EL jars are also available via java.net's Maven repository.

What are the differences between Server and Client side state saving and what are the benefits/drawbacks of each?

Server side state saving is where the component tree and all component state are stored within the user's session. This entry within the session is tracked by writing a key in the response that is used to lookup the entry on subsequent post-backs.

Client side state saving doesn't leverage the server side session mechanism at all, instead, the component tree and state will be serialized using Java Serialization, GZIP compressed (at least that is the default), Base64 encoded, and written to the response. When a post-back occurs, the encoding process will be reversed which will result in the tree and state we started with.

As to the benefits/drawbacks, review the following table.

Mojarra has three context initialization parameters that affect client side state saving:

• com.sun.faces.compressViewState - Defaults to true. If disabled, GZIP compression will not be used
• com.sun.faces.clientStateWriteBufferSize - Defaults to 8192. This parameter specifies the size, in bytes, of the buffer that is used to write client state. It should be noted, that the buffer is split - half is for raw bytes, the other half is for the Base64 encoded characters of said bytes. So, for example, if the default, 8192, is used, then 4096 of that is used for the bytes, and the other 4096 is used for the Base64 encoded characters. This is 8192, per request. Depending on the average complexity of the views in the application, this parameter may be adjusted up or down as appropriate.
• com.sun.faces.serializationProvider - This parameter specifies a class that implements the SerializationProvider SPI. This implementation represents a hook the JSF implementation will use in order to allow the use of alternate Serialization implementations.

There are four context initialization parameters for server side state saving:

• com.sun.faces.numberOfViewsInSession - Defaults to 15. This parameter defines the maximum number of JSF views stored in the session for per logical view. The map used to store the views uses an LRU algorithm to keep the map from growing beyond the configured value.
• com.sun.faces.numberOfLogicalViews - Defaults to 15. This parameter defines the maximum number of logical views to store per session. The map used to store the logical views uses an LRU algorighm to keep the map from growing beyone the configured value.
• com.sun.faces.serializeServerState - Defaults to false. When set to true, the state for the view will be serialized within the session. This may be desirable in the case where view state is sensitive to model changes (as of 1.2_08)
• com.sun.faces.compressViewState - Defaults to true. This option is only taken into account when com.sun.faces.serializeViewState is set to true. Compressing the serialized view state shows a significant reduction in retained memory for the server state within the session. This reduction in memory comes at the cost of increased CPU utilization (mostly from the serialization). This compression flag is only considered in 1.2_09 or later.

A comment on the numberOfXXX parameters. Logical views are best defined as top level view that may have one or more actual views inside of it. A new logical view entry will be created any time a GET occurs (a new request, a frameset, two browser windows...). The value of this logical entry is another Map that will be used to store the view information (i.e. the structure and state). As a user progresses through an application using standard JSF navigation mechanisms, additional view state will be added to the Map associated with a single logical view.

As an example, using the jsf-guessNumber application.

• First request results in a state marker value of j_id1:j_id2. j_id1 represents the logical view, and j_id2 represents the actual view state.
• Next, enter a guess. The new state marker value is j_id1:j_id3 - again j_id1 being the logical view, and j_id3 being the actual view. So at this point, the Map associated with logical view j_id1 has two entries, j_id2, and i_id3.
• Next, click the Back button, and the new marker is j_id1:j_id4.
• Now, issue a request to the context root of the application and notice that the state marker has now changed to j_id5:j_id6. As stated above, each GET will cause a new logical entry to be created. At this point, there are two logical Maps, j_id1 and j_id5. Logical Map j_id1, has three entries, j_id2, j_id3, and j_id4. Logical Map j_id5, has a single entry, j_id6.

How can I secure view state when using client side state saving?

By default, view state will not be encrypted. However, there is a way to do this within the Mojarra.

Specify a environment entry like so:

    <env-entry>
        <env-entry-name>com.sun.faces.ClientStateSavingPassword</env-entry-name>
        <env-entry-type>java.lang.String</env-entry-type>
        <env-entry-value>[SOME VALUE]</env-entry-value>
    </env-entry>

The presence of this JNDI entry will cause the state to be encrypted using the specified password. We realize this isn't the most secure way of conveying a password, however, this cannot be accessed easily without having code executed on the server side.

Why doesn't my navigation rule trigger a matching security constraint?

This occurs because security constraints aren't applied by the container when using RequestDispatcher.forward() as the default NavigationHandler implementation will do. In order to overcome this, you must configure the navigation to perform a redirect instead. You can do this by adding an empty redirect element to the rule.

Do I have to use a JSP 2.1/Servlet 2.5 container with the Mojarra version 1.2?

If you're using JSPs for your view descriptions, then yes, you will need to use a JSP 2.1/Servlet 2.5 compliant container. However, if you're using another view technology, such as Facelets or JSFTemplating, you can run JSF 1.2 within a Servlet 2.4 container with out issue.

How does resource injection with the Mojarra work?

First, some general webtier resource injection information can be found here. This documents what all EE5 containers will provide at the webtier level. This provides some basic examples that should get the typical application developer started.

I'm trying to integrate the Mojarra 1.2 with our EE5 container, but resource injection of managed beans doesn't work. Why?

Mojarra doesn't provide it's own resource injection mechanism. Instead, it exposes an InjectionProvider SPI that container vendors can implement which will allow Mojarra to take advantage of the container's resource injection mechanisms. This blog entry covers the details of the SPI and how it works.

That said, Mojarra includes InjectionProviders for the following containers: GlassFish, Tomcat 6, and Jetty 6.

It should be noted that in all cases what can be injected in a ManagedBean is purely a semantic of what the host container supports. If you're application was written with JavaEE 5 in mind, the application would be portable to all EE5 compliant containers, but may not run in, say, Tomcat 6 or Jetty 6. In those two cases, we only inject what the container itself supports.

I want to use Mojarra with Google App Engine (GAE)

There are instructions for this at this site .

I want to use Mojarra 1.2 in Glassfish v3

Include a sun-web.xml file in the war that has the following lines:

<class-loader delegate="false"/> 
<property name="useBundledJsf" value="true" />

and bundle Mojarra 1.2 into the WAR as well, and it should work.

I want to use Mojarra 2.0 in Glassfish v2 (or Sun App Server 9.1)

For a per-app basis, do this:

Include a sun-web.xml file in the war that has the following lines:

<sun-web-app>
<class-loader delegate="false"/>
<property name="useMyFaces" value="true"/>
</sun-web-app>

and bundle Mojarra 2.0 into the WAR as well, and it should work.

For upgrading the whole app server to Mojarra 2.0, see the release notes

I want to use Mojarra 2.0 with the new EL in Tomcat

Please see Cay's blog on the topic

Mojarra 2.0.0 Schedule

Mojarra 2.0.0 Schedule

This page (revision-74) was last changed on 21-Jan-10 10:11 AM, -0800 by JimDriscoll.
This page was created on 19-Mar-07 12:46 PM, -0700 by Jason Lee.

More info...