IFW2 -

HOW TO build your own ifw2 application

IFW2 requires a 2.5 compliant servlet container such as TOMCAT 6 or IBM WebSphere 7 with a JSE 6 jvm.

Include in your own ear/war file the ifw2.jar file with all of its dependencies.

The web.xml

Ensure that your web.xml file includes the following entries:

Declare the ifw2 mandatory initialization listener and:

acceptedLocales are locales accepted by your application, ie. locales for which you provide translations.
defaultLocale is the default locale supported by your application, ie. the locale used if the user browser does not recognise one of the acceptedLocales

  <context-param>
    <param-name>ifw2.acceptedLocales</param-name>
    <param-value>en_US,en_GB,it_IT</param-value>
  </context-param>
  <context-param>
    <param-name>ifw2.defaultLocale</param-name>
    <param-value>en_US</param-value>
  </context-param>
  ...
  <listener>
    <listener-class>net.infordata.ifw2.web.util.InitListener</listener-class>
  </listener>

Optional: include it if you don't want that current forms (ie. forms with focus) are "more" visible than others (the "more" visible effect depends on the browser type and is controlled via css style class "currentForm").

  <context-param>
    <param-name>ifw2.enhanceCurrentFormVisibility</param-name>
    <param-value>false</param-value>
  </context-param>

Optional: include them if you are using jpa and you plan to get access to the jpa Entity Manager through the net.infordata.ifw2.web.jpa.JpaUtil helper class.

The filter context-param "persistenceUnitNames" is optional if you are using only one persistence unit.

  <context-param>
    <param-name>ifw2.persistenceUnitName</param-name>
    <param-value>defaultPersistenceUnitName</param-value>
  </context-param>
  <context-param>
    <param-name>persistenceUnitNames</param-name>
    <param-value>defaultPersistenceUnitName, otherPersistenceUnitName</param-value>
  </context-param>
  ...
  <listener>
    <listener-class>net.infordata.ifw2.web.jpa.InitListener</listener-class>
  </listener>
  <filter>
    <filter-name>jpa</filter-name>
    <filter-class>net.infordata.ifw2.web.jpa.JpaFilter</filter-class>
  </filter>

Declare the ifw2 http-requests intercepting filter.

  <filter>
    <filter-name>httpRequest</filter-name>
    <filter-class>net.infordata.ifw2.web.util.HttpRequestFilter</filter-class>
    <init-param>
      <param-name>dump</param-name>
      <param-value>false</param-value>
    </init-param>
  </filter>

Optional: include it if you want to compress delivered html and text content. Useful in case of slow connections.

  <filter>
    <filter-name>compression</filter-name>
    <filter-class>net.infordata.ifw2.web.util.CompressionFilter</filter-class>
    <init-param>
      <param-name>compressionThreshold</param-name>
      <param-value>2048</param-value>
    </init-param>
    <init-param>
      <param-name>bufferSize</param-name>
      <param-value>8192</param-value>
    </init-param>
  </filter>

Declare the ifw2 multi-part http-requests intercepting filter.

It is used to handle multipart requests, ie. file uploads. It must be included even if your application does not handle file uploads.

  <filter>
    <filter-name>multipart</filter-name>
    <filter-class>net.infordata.ifw2.web.mpart.MultipartFilter</filter-class>
    <init-param>
      <param-name>dump</param-name>
      <param-value>false</param-value>
    </init-param>
  </filter>

Map declared filters.

Remove any optional filter you do not plan to use.

The order is very important and httpRequest must always be the first one.

  <filter-mapping>
    <filter-name>httpRequest</filter-name>
    <url-pattern>/ifw2/*</url-pattern>
  </filter-mapping>
  <filter-mapping>
    <filter-name>compression</filter-name>
    <url-pattern>/ifw2/*</url-pattern>
  </filter-mapping>
  <filter-mapping>
    <filter-name>multipart</filter-name>
    <url-pattern>/ifw2/*</url-pattern>
  </filter-mapping>
  <filter-mapping>
    <filter-name>jpa</filter-name>
    <url-pattern>/ifw2/*</url-pattern>
  </filter-mapping>

Add references to JSPs used for rendering.

In the following example we use the servlet-class tag to refer to precompiled tomcat-only jsp.

If you are using any other web container (such as IBM WebSphere 7) or if you want to personalize the default ifw2 rendering follow these steps :

extract the jsp files from the ifw2 jar file
place them in your WEB-INF/jsp/ifw2 directory
replace the <servlet-class> entry with (for example): <jsp-file>/WEB-INF/jsp/ifw2/DialogBox.jsp</jsp-file>

  <servlet>
    <servlet-name>errorPage</servlet-name>
    <servlet-class>net.infordata.ifw2.web.jsp.Error_jsp</servlet-class>
  </servlet>
  <servlet>
    <servlet-name>ifw2.template</servlet-name>
    <servlet-class>net.infordata.ifw2.web.jsp.Template_jsp</servlet-class>
  </servlet>
  <servlet>
    <servlet-name>ifw2.ecsRenderer</servlet-name>
    <servlet-class>net.infordata.ifw2.web.jsp.ECSRenderer_jsp</servlet-class>
  </servlet>
  <servlet>
    <servlet-name>ifw2.modalFooter</servlet-name>
    <servlet-class>net.infordata.ifw2.web.jsp.ModalFooter_jsp</servlet-class>
  </servlet>
  <servlet>
    <servlet-name>ifw2.dialogBox</servlet-name>
    <servlet-class>net.infordata.ifw2.web.jsp.DialogBox_jsp</servlet-class>
  </servlet>
  <servlet>
    <servlet-name>ifw2.taskBox</servlet-name>
    <servlet-class>net.infordata.ifw2.web.jsp.TaskBox_jsp</servlet-class>
  </servlet>
  <servlet>
    <servlet-name>ifw2.messageArea</servlet-name>
    <servlet-class>net.infordata.ifw2.web.jsp.MessageArea_jsp</servlet-class>
  </servlet>
  <servlet>
    <servlet-name>ifw2.tabbed</servlet-name>
    <servlet-class>net.infordata.ifw2.web.jsp.Tabbed_jsp</servlet-class>
  </servlet>
  <servlet>
    <servlet-name>ifw2.calendar</servlet-name>
    <servlet-class>net.infordata.ifw2.web.jsp.Calendar_jsp</servlet-class>
  </servlet>
  <servlet>
    <servlet-name>ifw2.dataGrid</servlet-name>
    <servlet-class>net.infordata.ifw2.web.jsp.DataGrid_jsp</servlet-class>
  </servlet>
  <servlet>
    <servlet-name>ifw2.editableGrid</servlet-name>
    <servlet-class>net.infordata.ifw2.web.jsp.EditableGrid_jsp</servlet-class>
  </servlet>
  <servlet>
    <servlet-name>ifw2.treeGrid</servlet-name>
    <servlet-class>net.infordata.ifw2.web.jsp.TreeGrid_jsp</servlet-class>
  </servlet>
  <servlet>
    <servlet-name>ifw2.popupMenu</servlet-name>
    <servlet-class>net.infordata.ifw2.web.jsp.PopupMenu_jsp</servlet-class> 
  </servlet>
  <servlet>
    <servlet-name>ifw2.menuBar</servlet-name>
    <servlet-class>net.infordata.ifw2.web.jsp.MenuBar_jsp</servlet-class> 
  </servlet>

Declare the ifw2 main servlet.

  <servlet>
    <servlet-name>ifw2</servlet-name>
    <servlet-class>net.infordata.ifw2.web.util.MainServlet</servlet-class>
    <init-param>
      <param-name>layout</param-name>
      <param-value>/WEB-INF/jsp/Layout.jsp</param-value>
    </init-param>
  </servlet>

Declare servlets to serve ifw2 static resources such as images, css or javascript.

They are retrieved directly from the ifw2.jar, but you can override this default behavior by replacing <param-name>resource</param-name> with <param-name>warResource</param-name> or <param-name>url</param-name>

  <servlet>
    <servlet-name>staticRes</servlet-name>
    <servlet-class>net.infordata.ifw2.web.util.StaticResourceServlet</servlet-class>
    <init-param>
      <param-name>resource</param-name>
      <param-value>/net/infordata/ifw2/web/resources/base.gif</param-value>
    </init-param>
  </servlet>
  <servlet>
    <servlet-name>jsClient</servlet-name>
    <servlet-class>net.infordata.ifw2.web.util.JSServlet</servlet-class>
    <init-param>
      <param-name>resource</param-name>
      <param-value>/net/infordata/ifw2/web/js/Client.js</param-value>
    </init-param>
    <init-param>
      <param-name>immediatePurge</param-name>
      <param-value>false</param-value>
    </init-param>
    <init-param>
      <param-name>enableUriTracking</param-name>
      <param-value>false</param-value>
    </init-param>
  </servlet>
  <servlet>
    <servlet-name>cssStyles</servlet-name>
    <servlet-class>net.infordata.ifw2.web.util.CSSServlet</servlet-class>
    <init-param>
      <param-name>resource</param-name>
      <param-value>/net/infordata/ifw2/web/css/Styles.css</param-value>
    </init-param>
  </servlet>
  <servlet>
    <servlet-name>jsStyles</servlet-name>
    <servlet-class>net.infordata.ifw2.web.util.CSSServlet</servlet-class>
    <init-param>
      <param-name>resource</param-name>
      <param-value>/net/infordata/ifw2/web/css/Styles.js</param-value>
    </init-param>
  </servlet>

Optional: declare servlets to serve your application static resources.

  <servlet>
    <servlet-name>appStaticRes</servlet-name>
    <servlet-class>net.infordata.ifw2.web.util.StaticResourceServlet</servlet-class>
    <init-param>
      <param-name>warResource</param-name>
      <param-value>/WEB-INF/resources/base.gif</param-value>
    </init-param>
  </servlet>

Declare your own main application servlet which is in charce of setting up the main flow.

  <servlet>
    <servlet-name>main</servlet-name>
    <servlet-class>test.ui.MainServlet</servlet-class>
  </servlet>

Map servlets to serve ifw2 static resources such as images, css or javascript.

The url-pattern cannot be changed since it is hard-coded in ifw2.

  <servlet-mapping>
    <servlet-name>staticRes</servlet-name>
    <url-pattern>/ifw2.static/*</url-pattern>
  </servlet-mapping>
  <servlet-mapping>
    <servlet-name>jsClient</servlet-name>
    <url-pattern>/js/Client.js</url-pattern>
  </servlet-mapping>
  <servlet-mapping>
    <servlet-name>cssStyles</servlet-name>
    <url-pattern>/css/Styles.css</url-pattern>
  </servlet-mapping>
  <servlet-mapping>
    <servlet-name>jsStyles</servlet-name>
    <url-pattern>/css/Styles.js</url-pattern>
  </servlet-mapping>

Optional: map servlets to serve your application static resources.

  <servlet-mapping>
    <servlet-name>appStaticRes</servlet-name>
    <url-pattern>/app.static/*</url-pattern>
  </servlet-mapping>

Map the ifw2 main servlet.

The application url entry-point will be: <context-root>/<ifw2-main-servlet-url-pattern>/<application-main-servlet-name>, e.g. warContextRoot/ifw2/main

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

Map the ifw2 default error handling servlet and declare it as the default error-page.

  <!-- main error handling -->  
  <servlet-mapping>
    <servlet-name>errorPage</servlet-name>
    <url-pattern>/errorPage</url-pattern>
  </servlet-mapping>
  <error-page>
    <exception-type>java.lang.Throwable</exception-type>
    <location>/errorPage</location>
  </error-page>

Declare the ifw2 tag library.

  <jsp-config>
    <taglib>
      <taglib-uri>http://www.infordata.net/taglibs/ifw2</taglib-uri>
      <taglib-location>/WEB-INF/lib/ifw2.jar</taglib-location>
    </taglib>
  </jsp-config>

Optional: declare any data source required by your application.

  <resource-ref>
    <res-ref-name>jdbc/MyDB</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
    <res-sharing-scope>Unshareable</res-sharing-scope>
  </resource-ref>

Optional: declare the mail session used by the default ifw2 error handling servlet to send e-mail notifications about unhandled application errors.

E-mail destinations are retrived from the app-server environment variable named: ifw2/error/destinations (in tomcat declare it in the server.xml file with the Environment tag).

  <resource-ref>
    <res-ref-name>ifw2/error/mailSession</res-ref-name>
    <res-type>javax.mail.Session</res-type>
    <res-auth>Container</res-auth>
  </resource-ref>

Optional: add security related entries.

  <security-constraint>
    <web-resource-collection>
      <web-resource-name>ReservedArea</web-resource-name>
      <url-pattern>/ifw2/*</url-pattern>
      <http-method>GET</http-method>
      <http-method>POST</http-method>
      <http-method>HEAD</http-method>
    </web-resource-collection>
    <auth-constraint>
      <role-name>*</role-name>
    </auth-constraint>
    <user-data-constraint>
      <transport-guarantee>NONE</transport-guarantee>
    </user-data-constraint>
  </security-constraint>
  
  <login-config>
    <auth-method>FORM</auth-method>
    <realm-name>me.com</realm-name>
    <form-login-config>
      ...
    </form-login-config>
  </login-config>
  
  <security-role>
    <role-name>User</role-name>
  </security-role>

The main servlet

Write your application main servlet which as been declared in web.xml as follow.

Basically it is used to register a prototype instance of the main-flow (see How to create a "composite" flow). For each user session there will be a clone of the original main-flow instance, this is ensured by the IFW2 framework.

package test.ui;

import javax.servlet.ServletConfig;
import javax.servlet.ServletException;

import net.infordata.ifw2.web.ctrl.FlowRequestHandler;
import net.infordata.ifw2.web.ctrl.PageControllerServlet;
import net.infordata.ifw2.web.ctrl.SimpleRequestHandlerFactory;
import net.infordata.ifw2.web.view.RendererEngine;

public class MainServlet extends PageControllerServlet {

  private static final long serialVersionUID = 1L;

  @Override
  public void init(ServletConfig config) throws ServletException {
    super.init(config);
    MainFlow flow = new MainFlow();
    
    registerRequestHandlerFactory(
        new SimpleRequestHandlerFactory(
            new FlowRequestHandler(flow, 
                new RendererEngine("Main", flow))));
  }
}

Get IFW2

About IFW2

Community

Development

Documentation

HOW TO build your own ifw2 application

The web.xml

The main servlet