ICEfaces Java Studio Creator 2 Integration

v1.5 (Early Access) Release Notes

November 2006

logo


Contents

Overview
Requirements
ICEfaces Extension for Java Studio Creator 2
ICEfaces Component Suite Complib for JSC2
Upgrading from a Previous Version
Using ICEfaces Data Table and data binding with JSC2
Tips
Known Issues
Support
License


Overview

The ICEfaces Java Studio Creator 2 (JSC2) integration provides ICEfaces support for developers who use JSC2 IDE for web application development. The ICEfaces integration consists of two parts:

1.      A JSC2 extension that provides runtime library support for ICEfaces and support for wizards for starting new ICEfaces JSF projects or converting an existing JSF project to ICEfaces. 

2.      A JSC2 component library (complib) file that provides support for using the ICEfaces Component Suite components at design time. The complib is included in the JSC2 extension. It will be automcatically imported into the Component library Manager when you create a new ICEfaces JSF Project in the first time.

Note: This release is designated Early Access (EA). While it provides most of the functionality of the final release, there are still some missing features, known issues, and a lack of refinement in some areas. Please review the Known Issues section prior to using this integration.

If you are upgrading from a previously installed ICEfaces JSC2 integration, refer to the upgrade instructions.


Requirements

The ICEfaces extension requires Sun Java Studio Creator 2, Update 1.  Java Studio Creator 2 is available as a free download from the Sun Studio Creator Web site. It is highly recommended that you become familiar with using Java Studio Creator for JSF web application development prior to using ICEfaces with JSC2.

To successfully use the ICEfaces Component Suite components with JSC2, you must use them in conjunction with the following JSC2 webui components:

Because JSC2 requires the use of these components for design time support, the ICEfaces extension includes ICEfaces Direct-to-DOM renderers that enable them to work correctly with the ICEfaces Component Suite.

Note: No other webui "ui:" components are supported at this time. In practice, this means that any ICEfaces applications developed using JSC2 must also use these webui components. Thus, all applications must use these JSC2 webui component runtime JARs at deployment/runtime.

ICEfaces Extension for Java Studio Creator 2

The ICEfaces extension for Java Studio Creator provides ICEfaces runtime support for developers who use the JSC2 IDE for web application development. The JSC2 extension provides the following capabilities:

After installing the extension, additional ICEfaces-related options appear on the context menu in the file view of the project, facilitating conversion of existing JSF projects to ICEfaces-enabled JSF projects.

Installing the ICEfaces Extension for JSC2

  1. Start Java Studio Creator 2.
  2. From the main menu, select Tools > Update Center.
  3. Select Install Manually Downloaded Module (.nbm Files).
  4. Click Next.
  5. Click Add, and then browse to the .../install_dir/creator2/creator2 directory where the com.icesoft.ide.creator2.project.ICEfacesLibraryPlugin.nbm file is located.
  6. Select the file and click OK.
  7. Click Next.
  8. Select Include Option.
  9. Click Yes to allow the installation of the extension.

Using the New ICEfaces JSF Project Wizard

  1. From the main menu, select File > New project. (You can also click Create New Project in the Welcome window.)
  2.  In the New Project Wizard, click Next, type in your project category in the Web or Samples category.
  3. Type in your project name and click Finish.
A new JSF Project with ICEfaces preconfigured is created under the Web directory.

Converting an Existing JSF Project into an ICEfaces Project

  1. Create a JSF project if you do not already have one.
  2. In the Project File view, under the Web Projects node, right-click the project node and select ICEfaces Intergration from the context menu.
  3. To add the ICEfaces entries to the web deployment file (web.xml), click Yes in the confirmation dialog.

The project should now have all required icefaces JARs and configuration entries added to the existing web.xml.

Viewing the ICEfaces Sample Applications

  1. From the main menu, select File > New project. (You can also click Create New Project in the Welcome window.)
  2. In the New Project Wizard under Samples, select the ICEfaces sample application that you want to view.

Uninstalling the ICEfaces Extension for JSC2

With Java Studio Creator 2 Update 1, the ICEfaces files are located under the ../rave2.0 directory (for example, under Linux /opt/sun/Creator2_1/rave2.0/).

To completely uninstall the ICEfaces JSC2 integration, you must have JSC2 shutdown and then complete the following steps:

  1. Remove these files in the following order:
  2. When you are done removing the files, remove the ./modules/ext/icefaces directory.

ICEfaces Component Suite Complib for JSC2

The ICEfaces Component Suite JSC2 component library (Complib) provides support for the ICEfaces Component Suite in the JSC2 design time visual editors. It reduces the complexity of building interactive web pages and speeds up the development cycle by allowing developers to leverage the design time visual editor support in JSC2 to develop rich web applications with ICEfaces.

The ICEfaces Component Library depends on the ICEfaces Java Studio Creator 2 (JSC2) extension which provides the required ICEfaces Runtime Support Library and deployment description configuration.

Installing the ICEfaces Complib

ICEfaces Complib is included in ICEfaces Extension for JSC2. It will be imported into Component Library Manager when you create a new ICEfaces JSF project in the first time. No separate import component library required.

Using the ICEfaces Component Suite at Design Time

To use the ICEfaces Component Suite in JSC2 in the "Design" editor, you must first create a JSP page skeleton using the JSC2 Webui components listed in the Requirements section. Once you have a suitable JSP page created, you may:

  1. Drag an ICEfaces component from the JSC2 Component Palette under the "ICEfaces Component Suite" category and drop it onto the page.
  2. Select an ICEfaces component by clicking on it, then use the context menu or the Properties sheet to view/edit the selected component properties.
  3. Use the other component viewing/editing facilities provided by JSC2.

The ICEfaces Component Suite component tags will also be recognized in the JSC2 JSP editor. All standard JSP editing features such as JSP completion and syntax awareness are supported.
 

Uninstalling the ICEfaces Complib

  1. Click the Components tab of the Palette.
  2. Right-click a category and choose Manage Component Libraries.
  3. In the Component Library Manager, select the library you want to delete and click Remove at the bottom of the window.
  4. Select Yes to confirm the deletion.
The components disappear from the Palette. If you previously added any of these components to pages, those components are not affected.

Upgrading from a Previous Version

If you are upgrading your ICEfaces JSC2 Integration from a previous version, you must perform the following steps for a successful upgrade:

  1. Uninstall both the ICEfaces JSC2 Complib and the JSC2 Extension.
  2. On Windows only, manually remove the JSC2 internal cache files or the installation of the newer extension library will fail silently.
  3. With JSC2 shutdown, delete the following directory:
  4. If you have existing ICEfaces JSC2 projects that you would like to upgrade to use the new ICEfaces runtime and component JARs, delete the following directory for each affected project:

Using ICEfaces Data Table and data binding with JSC2

The following instructions assume that you are familiar with Java Studio Creator and that you have already created your project.

1. Open your project using Java Studio Creator.

2. From the Components Palette, right-click the dataTable and select Bind to Database.

The following screen image shows the context menu for the dataTable.

For detailed instructions for Binding a Data Table Component to a Database Table, refer to the Sun Studio Creator Web site at http://developers.sun.com/prodtech/javatools/jscreator/reference/techart/2/bindingDataTableComponents.html

3. Select the Table component and then right-click Table Layout from the context menu.

4. In the Table Layout dialog box, click the Paging tab and check Enable Paging. Specify the number or rows and modify other display options. When you are done, click OK.

5. Use the context menu items (for example, Add UIColumn, Add RowSelector, etc.) to add ICEfaces components to the dataTable. Refer to the ICEfaces Component Suite for additional information on components.

6. To add a SortHeader to a dataTable, right-click and select Bind to Database. For additional information, refer to the Sun Studio Creator Web site at http://developers.sun.com/prodtech/javatools/jscreator/reference/techart/2/bindingDataTableComponents.html

and to:

http://developers.sun.com/prodtech/javatools/jscreator/reference/fi/2/data-providers.html

Before adding a sortHeader, you need to bind a RowSet to the Data Table. Drag the table component onto a page, then drag a data source table (for example, PERSON) onto that Table component. The IDE not only binds the PERSON data table to the Table component, automatically changing its column headings to match the table fields, but also adds a RowSet (personRowSet) to SessionBean1 and a Data Provider (personDataProvider) to the page. You can see these two components in the Outline within SessionBean1 and the page.

Refer to http://developers.sun.com/prodtech/javatools/jscreator/reference/index.jsp for more information.

By default the commandSortHeader component is used in conjunction with a Data Table and CachedRowSetSortableDataModel in design time. The commandSortHeader renders a clickable column header facet allowing the user to toggle the sort order of data in the table, either ascending or descending based on the values in the column. The commandSortHeader can be used to provide a user-controlled data sorting capability to a dataTable.

7. To select items to bind to the database, right-click an item (for example, selectManyMenu, selectManyList, selectOneMenu, etc.) in the Outline tree view.

The following screen image shows the context menu for a selectItems inside selectManyMenu:

The following screen image shows the context menu for a selectItems inside selectManyCheckbox:

8. Select a related Value field and Display field items and click Apply.

The following screen image shows the Bind List Items to Database dialog box.

For more details, refer to http://developers.sun.com/prodtech/javatools/jscreator/reference/techart/2/checkbox_component.html

9. You can use the dataPaginator component to handle table pagination. In the Palette pane, select the Data Table and drag the DataPagination componet onto the table.

10. In the Palette pane, select PanelTabSet, and then drag it onto the design panel or tree view. If you click a tab while designing your web page, that tab becomes the selected tab.

11. You can bind most input and output components to data objects. Binding a component to data enables the web application to automatically synchronize the component's value with the value of the binding target. For example, if you bind a component to a bean property, the web application sets the component's value to the bean property's value when the application renders the page, and when the page is submitted, the web application changes the bean property's value to match changes made to the component's value.

 

The following screen image shows a default databean (selectOneRadioDefaultItem):

12. You can change the look and feel in the design time and runtime for your project by attaching a stylesheet. Use xp_dt.css as the design time stylesheet and xp.css as the runtime stylesheet.

Add the <ice:outputStyle> stylesheet and change the <href> attribute from the Properties view with ./xmlhttp/css/xp/xp.css. The strict path is required ./xmlhttp/css/xp/xp.css.


Tips

Sun Application Server Memory heap size

domain.xml cluster

Performance can suffer due to the overhead required to manage limited memory.

Setting JVM Heap size for Sun Application Server.

/opt/sun/Creator2_1/SunAppServer8/domains/creator/config/domain.xml

     <jvm-options>-XX:PermSize=64m</jvm-options>

       <jvm-options>-XX:MaxPermSize=256m</jvm-options>

For more detailed information, please refer to http://java.sun.com/docs/hotspot/VMOptions.html

Setting JVM Heap size for Creator 2       

D:\Program Files\Sun\Creator2_1\etc\creator.conf

netbeans_default_options="-J-Xms128m -J-Xmx512m -J-XX:PermSize=128m -J-XX:MaxPermSize=256m

You should set your maximum Java heap size so that the total memory consumed by all the JVMs running on the system does not exceed the memory capacity of your system.      

For more detailed information about turn Creator 2 to work with large applications, please reference to http://developers.sun.com/prodtech/javatools/jscreator/reference/faqs/technical/tshooting/index.jsp

Reset Sun Application Server

Only necessary if you want to reset Sun Application Server.

D:\Program Files\Sun\Creator2_1\bin\pe-start -reset

It will rebuild default domain. All deployed applications will be deleted.

For more detailed information, please refer to http://docs.sun.com/source/819-0215/index.html

Setting Logging Level with ICEfaces in Design Time

Running Creator 2 with default JVM, logging.properties can be found under following:

D:\Program Files\Sun\Creator2_1\java\jre\lib\logging.properties

You need to add the following logging level:

com.icesoft.faces.level = FINEST

For more detailed information about JDK logging, please reference to http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html

For more detailed information about log file in Creator 2 or the deployment server, please reference to http://developers.sun.com/prodtech/javatools/jscreator/reference/faqs/technical/tshooting/index.jsp

How to deploy to Tomcat:

Export the project from the IDE as a war file. and Deploy the application by copying its WAR file into tomcat-install-directory/webapps.

For more detailed, please refer to http://developers.sun.com/prodtech/javatools/jscreator/reference/docs/help/2update1/deploy/howtodeploy/deploy_tomcat.html


Known Issues

The following are known issues in this release:

For example:

<navigation-case>
               <from-outcome>case1</from-outcome>
               <to-view-id>/Page2.jsp</toview-id>
               <redirect/>
</navigation-case>

Support

For help with this release, refer to http://support.icefaces.org which includes the ICEfaces knowledgebase including articles, slide shows, and other resources. In addition, refer to the ICEfaces support forums where you can monitor and participate in discussions on ICEfaces technology, tips, and techniques.

Additional commercial support is also available from ICEsoft Technologies Inc. Visit www.icesoft.com.


License Notice

License agreements can be found in the .../install_dir/creator2/icefaces/license directory.

Copyright 2005-2006. ICEsoft Technologies, Inc.