How-to configure Apache Trinidad components in Oracle JDeveloper

An Oracle JDeveloper How-to
Written by Frank Nimphius, Oracle Corporation
April, 2007

Downloading the Trinidad Binaries
Making the Trinidad libraries available in Oracle JDeveloper
Configuring Trinidad in Oracle JDeveloper
Creating an Oracle JDeveloper project for Trinidad
Building a Trinidad JSF page
Exploring the Trinidad source code
Compatibility of ADF Faces and Trinidad

Introduction

Trinidad is a set of JavaServer Faces UI components built on top of the JavaServer Faces API. Over a year ago, Oracle donated its ADF Faces components to the Apache open source community to become the starting point for Trinidad. Since then the MyFaces open source community at Apache has further developed Trinidad, striving towards the first official open source release. Just recently the Apache Trinidad 1.0.0-incubating distribution became publicly available on the Trinidad website.

It is important to understand that Trinidad is different from ADF Faces and a component set in its own right. Oracle is a major contributer and deeply involved in the development of the Trinidad components.

This article explains how to set up a JDeveloper project with the Trinidad binaries to explore the Trinidad components and to build JavaServer Faces web applications based on this open source component set.

Downloading the Trinidad Binaries

To configure Trinidad JavaServer Faces components in Oracle JDeveloper, download the Apache Trinidad 1.0.0-incubating distribution from the Apache incubator. Make sure you download both archive files, the binary distribution and the examples. The Trinidad example WAR file can be deployed to Oracle Containers for J2EE using Enterprise Manager. This sample application can be used to functionally explore the Trinidad components.

Figure 1: Trinidad downloads

Note: Just recently Trinidad has been approved to move out of incubator stage, which means that a first official release can be build. In the official release of Trinidad, which at the time of writing is not out yet, the trinidad-impl-1.0.0-incubating.jar file is renamed to apache-myfaces-trinidad-impl-1.0.1.jar.

Making Trinidad Component Libraries available in JDeveloper

To setup JDeveloper with Trinidad, open the trinidad-1.0.0-incubating-dist.zip file and extract all of the contained Java Archive files (JAR) to the Oracle JDeveloper10.1.3.2\jlib directory. The trinidad-1.0.0-incubating-dist.zip also contains the Trinidad component sources that will become accessible in JDeveloper for reading and debugging.

Figure 2: Trinidad Java Archives

Configuring Trinidad in Orace JDeveloper

In Oracle JDeveloper, select Tools | Manage Libraries from the menu. In the Manage Libraries dialog, select the User entry and press the New button. Select the Class Path entry and browse for the following JAR files in the Oracle JDeveloper10.1.3.2\jlib directory

• commons-beanutils-1.6.jar
• commons-collections-2.0.jar
• commons-logging-1.0.jar
• jsf-facelets-1.1.6.jar
• trinidad-api-1.0.0-incubating.jar
• trinidad-impl-1.0.0-incubating.jar

Figure 3: Configuring the Trinidad libraries in JDeveloper

Repeat the same steps for the Source Path entry and choose trinidad-impl-1.0.0-incubating-sources.jar and trinidad-api-1.0.0-incubating-sources.jar.

Select the JSP Tag Libraries tab, choose the User entry and press the New button to import the Trinidad JSP tag libraries. Select the trinidad-impl-1.0.0-incubating.jar in the JDeveloper10.1.3.2\jlib and close the dialog.

Figure 4: Selecting the tag libraries in trinidad-impl-1.0.0-incubating.jar

Select each of the two tag libraries and check the Execute Tags in JSP Visual Editor so the Trinidad components are rendered in the Oracle JDeveloper design view. If you don't do this then the components will be displayed as raw JSP tags.

Figure 5: Ensuring the Trinidad components are rendered in the visual editor

Creating an Oracle JDeveloper project for Trinidad

In Oracle JDeveloper, use the context menu to create a new Application.

Figure 6: Creating a new application in Oacle JDeveloper

In the application dialog, provide an application name, e.g. TrinidadWebApplication, a default package prefix and choose No Template [All Technologies] in the template selection field. In the Create Project dialog, define a project name, e.g. TrinidadViewLayer. Double click on the new project to open the project properties palette. Select the Technology Scope entry and choose JSF from the list of Available Technologies before pressing the button.

Select the Libraries entry and press the Add Library button. Choose the Trinidad library created before. Close the project properties dialog by pressing the Ok button. Oracle populates the project with a faces-config.xml JSF configuration file and a web.xml deployment descriptor file. Both files need editing to enable Trinidad components.

Configuring the web.xml and faces-config.xml files

The web.xml deployment descriptor contains the Trinidad servlet filter configuration while the faces-config.xml file contains the renderer kit used by Trinidad. Both files must be editor for, the visual editor in JDeveloper to show a WYSIWYG image of the Trinidad web page. Before starting to develop web applications with Trinidad components you need to configure both of these files.

web.xml

<?xml version = '1.0' encoding = 'ISO-8859-1'?>

<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4">
<context-param>
  <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
  <param-value>client</param-value>
  <!--param-value>server</param-value-->
</context-param>

<context-param>
  <param-name>org.apache.myfaces.trinidad.USE_APPLICATION_VIEW_CACHE</param-name>
  <param-value>false</param-value>
</context-param>

<context-param>
  <param-name>org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION</param-name>
  <param-value>true</param-value>
</context-param>

<context-param>
  <param-name>org.apache.myfaces.trinidad.CHANGE_PERSISTENCE</param-name>
  <param-value>session</param-value>
</context-param>

<filter>
  <filter-name>trinidad</filter-name>
  <filter-class>org.apache.myfaces.trinidad.webapp.TrinidadFilter</filter-class>
</filter>

<filter-mapping>
  <filter-name>trinidad</filter-name>
  <servlet-name>faces</servlet-name>
</filter-mapping>

<servlet>
  <servlet-name>faces</servlet-name>
  <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
</servlet>

<servlet>
  <servlet-name>resources</servlet-name>
  <servlet-class>org.apache.myfaces.trinidad.webapp.ResourceServlet</servlet-class>
</servlet>

<servlet-mapping>
  <servlet-name>faces</servlet-name>
  <url-pattern>/faces/*</url-pattern>
</servlet-mapping>

<servlet-mapping>
  <servlet-name>resources</servlet-name>
  <url-pattern>/adf/*</url-pattern>
</servlet-mapping>

</web-app>

faces-config.xml

<?xml version="1.0"?>
<!DOCTYPE faces-config PUBLIC "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN"
"http://java.sun.com/dtd/web-facesconfig_1_0.dtd" >
<faces-config>
   <application>
    <default-render-kit-id>
      org.apache.myfaces.trinidad.core
    </default-render-kit-id>
  </application>
</faces-config>

You can download eth commented sample web.xml and sample faces-config.xml files to copy and paste their content into the JDeveloper project's web.xml and faces-config.xml file, replacing the existing content. This gives you a head start in configuring Trinidad in an Oracle JDeveloper projects. Both sample configuration files are extracts from the demo files contained in trinidad-1.0.0-incubating-example.zip.

Save the project.

Building a Trinidad JSF page

In JDeveloper, double click onto the faces-config.xml file or choose Open JSF Navigation from the context menu on the project node. This opens the empty faces-config.xml file. Ensure that Diagram tab is selected. The Component palette should be opened automatically. If not, choose View| Component Palette from the JDeveloper menu or press ctrl+shift+P. Drag and drop JSF Page component to the faces-config.xml diagram.

Double click on the page icon to create the page. When navigating through the page creation wizard, ensure that you de-select the ADF Faces libraries in step 3 of the wizard.

Figure 7: De-selecting ADF Faces libraries when creating the JSF page

The first time you create a JSF page, the Trinidad libraries are not shown in the list of available libraries. Finish the page creation wizard and wait for the visual editor to show the empty JSF page. To make the Trinidad tag libraries available for the project, click anywhere in the Component palette using the right mouse button. From the context menu, select the Edit Tag Libraries option. In the opened dialog window, select the two Trinidad tag libraries and press the button to add them to the project.

Note: If you didn't de-select the ADF Faces libraries when first creating a new JSF page (Figure 7), the ADF Faces libraries are shown in the Component Palette dialog. If this is the case in your project, de-select the ADF Faces libraries as shown below (Figure 8) and remove the adf-faces-impl.jar file from the public_html/WEB-INF/lib directory of the view project.

Figure 8: Adding Trinidad tag libraries to the Component Palette

The Trinidad components are now available on the Component Palette and can be added to the JSF page using drag and drop.

Figure 9: WYSIWYG development with Trinidad in JDeveloper

Exploring the Trinidad Source Code

If you configured the source path for the Trinidad libraries, as explained previously in this doucment, then all Trinidad source-code is available in Oracle JDeveloper by pressing ctrl+ -.

Figure 10: Trinidad source code in Oracle JDeveloper

Compatibility of ADF Faces and Trinidad

In Oracle JDeveloper 10.1.3.x, Trinidad and ADF Faces components can not be used in the same project. When configuring a web project to use Trinidad components, ensure that ADF Faces components are de-selected and the adf-faces-impl.jar file is not contained in the WEB-INF/lib directory of the web project. If you experience runtime exceptions when testing your web application, first check if the WEB-INF/lib contains adf-faces-impl.jar. If it does, remove this file.

Summary

The Trinidad JavaServer Faces component set is available on the MyFaces website at Apache.org for developer testing. As a developer you have access to the Trinidad binaries and sources to get familiar with the software. This how-to document is aimed at developers that are interested in exploring Triniad components in Oracle JDeveloper, but are not yet ADF developers.