SunJSFImplFaq < Projects < TWiki

TWiki . Projects . SunJSFImplFaq

Frequently Asked Questions about Sun's JavaServer Faces Implementation

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

Questions applying to all versions of the implementation

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

General JSF-related questions


Questions applying to all versions of the implementation

Access to the source code for Sun's implementation of the JCP JSF Specification is under the conditions of the Common Development and Distribution License.

Click here to view and accept the CDDL license and apply for CVS access to the source.

Once you've accepted the license, and we have acknowledged your acceptance, you can access the source code in the javaserverfaces-sources sub-project of this project. Refer to the CVS instructions for details on configuring your CVS client.

o Ant 1.6.5 < http://jakarta.apache.org/ant/ >

o Junit 3.8.1 < http://www.junit.org >

o Cactus 1.4.1 (JSF 1.1) < http://jakarta.apache.org/cactus/ >

o Cactus 1.7.1 (JSF 1.2) < http://jakarta.apache.org/cactus/ >

o htmlunit 1.8 < http://htmlunit.sourceforge.net/ >

o Tag Library Documentation Generator 1.3 < http://taglibrarydoc.dev.java.net >

This is most probably caused by a request going to your server but not being picked up by the FacesServlet. Make sure you have properly mapped the FacesServlet. You need to follow the insructions in Writing the web.xml File and Invoking the FacesServlet in the JavaServer Faces Tutorial.

Install JUnit 3.8.1 from http://www.junit.org/. Copy the junit.jar into your %ANT_HOME%\lib directory.

Please note the following:

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 .

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:

  1. Make sure you are making changes in the most recent version of the sources.
  2. From the javaserverfaces-sources directory, run the command:

    cvs diff -u > somefilename.diff

    cvs update -d -P > somefilename.log

  3. somefilename.log lists all the files you modified. Describe the changes you made to each file providing as much detail as possible. This makes it easy for developers reviewing and committing your patch.
  4. Send your patch to dev@javaserverfaces.dev.java.net with issue id (if there is one) and a brief summary of the fix/feature as the subject.

    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.

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.

  1. 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 fill out the change-bundle template, deleting the text in []. Please refer to the issue "id" in the bundle and in the subject of your email.

  2. The module owner reviews the change bundle
  3. .

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

  1. cd to the top level of your workarea.
  2. 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.
    1. ant
    2. '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.

  3. Make sure jsf-guessNumber, jsf-cardemo, jsf-components demos run successfully.
  4. Run "ant test" on the jsf-demo directory. This will run the HTMLUnit automated tests on the demos.
  5. Once you have run all the tests successfully, you are ready to commit. Run this command

    cvs -n update -d -P

  6. 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.

  7. 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.
  8. 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.

Follow How can I contribute? and start contributing enough 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 [[#RunTests][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

  1. Learn which logger you want to turn on. If you look in com.sun.faces.util.Util you find some usefull constants for logging:

    FACES_LOGGER=javax.enterprise.resource.webcontainer.jsf:    It concerns every logger.

    Other logger constants are:

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

  2. 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

  3. 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>

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

o GlassFish https://glassfish.dev.java.net/ or any JSP2.1/J2EE 5.0 based container

o J2SE? 5.0 http://java.sun.com/j2se/1.5.0/index.jsp or later

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

  1. If you are planning on running the unit tests, copy $JUNIT_HOME/junit.jar to your $ANT_HOME/lib directory.
  2. Change directory to the location of the checked out source.
  3. Copy build.properties.glassfish to build.properties and set the following properties:

    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.

  4. 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.
  5. 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:
  6. Restart the server for the updates to take effect.
  7. 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.
  8. 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.HOEM/domains/domain1/autodeploy) or you can use the asadmin utility to deploy the war file.

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

  1. On the Mac OS X 10.4 Platform, you need to copy $JAVA_HOME/lib/ext/sunjce_provider.jar to glassfish.home/lib.
  2. Run ant test from jsf-api. This will run all API tests.
  3. If you have GlassFish running, stop the server. Run ant config.container. This performs the necessary configuration modifications. Restart the server.
  4. Run ant test from jsf-ri. This will run all RI tests.
  5. 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:
  6. 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.

    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.

  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.
  2. Attach
    NetBeans
    debugger. Use the following values for Attach and click on "OK".
  3. 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.

    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.

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

    Parameter name Deprecated name Description Default value
    com.sun.faces.numberOfViewsInSession com.sun.faces.NUMBER_OF_VIEWS_IN_SESSION Defines the maximum number of serialized views stored in the session. Works with server state saving. 15
    com.sun.faces.numberOfLogicalViews com.sun.faces.NUMBER_OF_VIEWS_IN_LOGICAL_VIEW_IN_SESSION    15
    com.sun.faces.preferXHTML com.sun.faces.PreferXHTML For the case where a browser supports xhtml and html without a quality. When enabled and this case occurs, then xhtml will be set as the content type. false
    com.sun.faces.compressViewState com.sun.faces.COMPRESS_STATE When true the view is compressed after it is serialized and before base64 encoded. Works with client state saving. true
    com.sun.faces.disableVersionTracking n.a. Version tracking detects 1.1 artifacts (FacesContext? or Application implementations as an example) within the 1.2 runtime. If you have a pure 1.2 environment, then you could disable it.  false
    com.sun.faces.compressJavaScript n.a. If true, then the JavaScript rendered by h:commandLink will be compressed to reduce the amount of whitespace transmitted in the response. If false then the JavaScript will be rendered to the client in a well formatted manner. true
    com.sun.faces.externalizeJavaScript n.a. When true a script element with a src attribute. This allows browsers to cache the JS resource instead of having to write it each time the page is accessed. false
    com.sun.faces.sendPoweredByHeader n.a. The servlet specification defines an optional header that can be sent by a container to communicate the version of the JSP/Servlet the response was generated by. If this is enabled, then JSF/1.2 is included in this header. true
    com.sun.faces.verifyObjects n.a. When true JSF makes sure all managed beans components,validators, etc can be instantiated by the runtime false
    com.sun.faces.validateXml n.a. When true JSF validates the configuration files. false
    com.sun.faces.displayConfiguration n.a. If true then all web configuration information (context initialization parameters and environment entries) will be written to the log. This is useful during development to confirm your application is configured as expected. Valid values for this parameter are true and false false
    com.sun.faces.injectionProvider n.a. This parameter specifies a class that implements the InjectionProvider SPI. This implementation represents a hook the JSF implementation will use to provide resource injection support. See the documentation of the InjectionProvider interface for more details NONE
    com.sun.faces.serializationProvider n.a. 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. See the documentation of the SerializationProvider interface for more details NONE
    com.sun.faces.managedBeanFactoryDecoratorClass n.a. Specifies decorator class for the managed bean factory. NONE
    com.sun.faces.responseBufferSize n.a. This parameter specifies the size, in bytes, of the buffer that is used to write all generated content exluding state. 4096
    com.sun.faces.clientStateWriteBufferSize n.a. This parameter specifies the size, in bytes, of the buffer that is used to write client state. It should be noted, that the buffer used 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. 8192
    com.sun.faces.writeStateAtFormEnd n.a. Per the renderkit doc specification, the state information for the view will be written out prior to closing the form tag. However, it may be desirable to have the state information written out after the opening form tag. If this is the case, specifiy this parameter in the web.xml with a value of false (@since 1.2_04). false

    - This is not necessary if you're using a milestone build of GlassFish UR1 or GlassFish V2. Edit your APPSERV_HOME/domains/<domain-name>/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.

    What are some FrameMaker tips?

    Here is a dump of Ed's collected Frame Crib Sheet

    How to deal with the spec in general

    Launch frame by double clicking on the book. Then open all the chapters.

    How to generate the PDF

    Update dates. On TitlePage?.fm update the expert draft version.

    Make sure page numbers are updated. File->Edit->Update Book, make sure all boxes are checked.

    File->Save as Book. Choose PDF type and location, and accept defaults in setting window, pressing Set on that window.

    How To tell FrameMaker to expand or not expand the TOC when generating the PDF.

    It's in the Settings window:

    expand-bookmarks.png

    How to deal with changebars

    How to get rid of them.

    Format->Document->Change Bars. Do this for each chapter.

    Revision tagging process

    When all of the work for a spec revision has been completed, check the work in, tag the workspace, then clear the changebars in all the chapters, and re-check in the files so they're ready for more revisions.

    Special character stuff

    The character catalog is accessed with the little "f" icon in the upper right hand corner of the inividual MDI window. The Default Font mode is the normal mode. The code mode is for code. The emphasis mode is for italics. Don't use the Italic button.

    Special paragraph stuff

    The paragraph catalog is like the character catalog, but it's a paragraph symbol that accesses it. Commonly used ones are:

    Paragraph is the default

    Code Bullet 1 is when quoting the API method and signature

    Bullet 1 is a bulletted list.

    *Codeline is nice for showing XML code. You have to hit the tab key one more time than you think.

    Tables

    Like word, but not as nice.

    How to do cross references in frame

    Make sure the both the source and target documents are loaded into Frame.

    Go to where you want to put the "source" of the reference, and usually, you type "please see". Right click and choose "Cross-Reference".

    In the "Cross-Reference" dialog, twiddle the "Document:" drop-down to choose the document in which the target resides.

    Twiddle the "Source Type" widget to say "Paragraphs"

    Twiddle the "Paragraph Tags" option list to choose the paragraph type, say "Head2" to which you want to refer. As you choose different paragraph types, the section headers should show up in the "Paragraphs" list, to the right. Choose the one you want!

    Twiddle the "Format" widget to show the right style, usually "SectionNumber&Title".

    Press Insert.

    Images

    If you can re-create those images as PCX files, you can import them in to the document and they should look good.

    How do you fix the PDF bookmarks to be correct?

    Here are the tags and their order:
    TitleText?
    .ChapTitle
    .ChapTitleC
    .ChapTitleP
    ..Head1
    ..Head1P
    ...Head2
    ...Head2P
    ....Head3
    ....Head3P

    To reorder them:

    1. Open the Book file.
    2. Open Format->Document->PDF Setup.
    3. Shift-click the right arrow button (--->) to remove all tags from the Include Paragraph box.
    4. Select the tags listed above click the left arrow button (<---) to move them to the Include Paragraph box.
    5. Adjust the bookmark levels according to the list above by selecting the tag and moving them with the << and >> buttons. For example, move the TitleText? tag all the way to the left by selecting TitleText? and clicking << until it moves to the far left of the Include Paragraph box. ChapterTitle? should be one click to the right of TitleText?. Head1 should be two clicks, and so on.
    6. Save the Book file.
    7. Generate the PDF.

    Conditional Text

    How to show/hide conditional text in frame.

    Frame doesn't strip it out, but you can show/hide conditional text before you generate the PDF.

    1. Open the Conditional Text dialog box by selecting Special>Condition Text....
    2. Click Show/Hide.
    3. Move Comment and any other conditional text you want hidden to the Hidden column.
    4. Click Set.

    The Show Condition Indicators checkbox toggles whether conditional text should use colors (on) or be black (off). For instance, the Comment conditional text setting makes the text red and underlined when Show Condition Indicators is checked.

    A tip on hiding all conditional text in a book:

    1. Follow the above steps to hide the conditional text in one of the chapter files.
    2. Open the book file.
    3. Select File>Import>Formats.
    4. In Import From Document select the chapter file you worked on.
    5. Uncheck all the boxes in Import and Update except Conditional Text Settings.
    6. Uncheck the boxes in While Updating, Remove.
    7. Click Import.

    How to add new conditional text

    1. Open the Conditional Text dialog box.
    2. Type the text you want conditionalized.
    3. Select the text.
    4. In the Conditional Text dialog box, double click, for instance, Comment from the Not In or As Is column to move it to the In column. This automatically selects the Conditional radio button in Currect Selection Is.
    5. Click Apply.

    If you are marking an entire paragraph as conditional text, make sure you select the paragraph marker (viewable when you select View>Text Symbols). If you don't, there will be empty lines in the book when you turn off the conditional text.

    How to search in conditional text

    1. Open the search dialog box (Edit>Find/Change).
    2. In the Find field select Conditional Text....
    3. Select the Conditional Text setting.
    4. Enter the search terms.
    5. Click Find.

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

    General JSF-related questions

    Component writing can be, at least at first, an almost overwhelming task. To make things a bit simpler, RI 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.

    -- Main.jdlee - 22 Jan 2007

    ----- Revision r50 - 23 Jan 2009 - 20:00:53 - Main.edburns