====================
PRELIMINARY changes 3.1.1 -> 3.1.2
====================

Tips for migration
------------------

* Tomcat setup
  o make sure that UTF-8 is the default encoding;
    for more information, please refer to the installation chapter of the documentation.

* migrating JSP applications
  o first of all, you have to update the WEB-INF directory of your application:
        cd %yourapp%
        ren WEB-INF OLD-WEB-INF
        mkdir WEB-INF
        xcopy %xapplication%/examples/jsp/property/WEB-INF WEB-INF
    and make sure that WEB-INF\web.xml reflects your configuration (TAMINO_URL etc.)
  o most JSP pages run without modifications ... except for three incompatible changes:
    o improved error checking
      Error checking in X-Application 3.1.2 has been improved to help detecting problems in
      JSP applications. However, this error checking might report problems in existing applications
      that have not been detected by previous version of X-Application. Here are the most prominent
      error situations that might arise:
      o duplicate request arguments
        X-Application 3.1.1 did not check for duplicate HTTP request parameters. For example,
        JSP pages with a hidden form field ":pagesize" *and* a link with
        href="next.jsp?:pagesize=10" have been accepted. X-Application 3.1.2 rejects these pages
        since there is no way to find out which of the two values has to be used.
      o base attribute in loop tags
        X-Application 3.1.1 silently ignored if the value specified in "base" did not exist.
    o JSP pages with ':goto' parameters have to adapted if your browse tag has a 'document'
      attribute. Example:
        <bdm:browse document="myList" module="myMod" pagesize="10">
        ...
        </bdm:browse>
        <input type="text" name=":goto"/>
      has to be changed to
        <bdm:browse document="myList" module="myMod" pagesize="10">
        ...
        </bdm:browse>
        <input type="text" name=":goto(myList)"/>
    o Accessing X-Application data:
      JSP pages that use embedded Java code to access X-Application data have to be adjusted
      since the JSP package has been heavily restructured. Example:
      Old page:
        ...
        <%@ page import="com.softwareag.xtools.xapplication.jsptaglib.*" %>
        <%@ page import="com.softwareag.xtools.xapplication.businessdocument.*" %>
        ...
        <%  ModuleInstance module = (ModuleInstance)pageContext.getAttribute("bdBook",PageContext.SESSION_SCOPE); %>
        <%  BusinessDocument document=module.getDocument(null); %>
        ... work with document ...
        
      New page:
        ...
        <%@ page import="com.softwareag.xtools.xapplication.jsp.*" %>
        <%@ page import="com.softwareag.xtools.xapplication.businessdocument.*" %>
        ...
        <%  SessionContext sessionContext = ServletSessionContext.getSessionContext(pageContext); %>
        <%  BusinessDocument document = sessionContext.getDocument(null); %>
        ... work with document ...
      See the section below for more details on individual changes.

o migrating tags
  If you have implemented you own tags derived from XBodyTag, you'll most likely have to adjust
  the following things:
  o rename com.softwareag.xtools.xapplication.jsptaglib import to
    com.softwareag.xtools.xapplication.jsp or com.softwareag.xtools.xapplication.jsp.taglib.
  o change the base class of your tag from XBodyTag to JspTag.
  o the former moduleInstance field has been renamed to sessionContext.
  o the pageContext field is no longer available. All information previously accessed via this
    pageContext is now available via sessionContext or requestContext.
    Note that information in these fields is restricted to those items actually needed by
    existing X-Application tags, if you need more informations, you have to extend the SessionContext
    or RequestContext classes. Ratinale: simplify unit testing for JSP tags by keeping the context
    as small as possible.

* migrating servlets
  Servlets that access X-Application data have to be adjusted since the JSP package has been
  heavily restructured. Example:

  Old code:
    import com.softwareag.xtools.xapplication.jsptaglib.*;
    
    public void doGet(HttpServletRequest req, HttpServletResponse resp)
        throws IOException, ServletException
    {
        ModuleInstance xapplicationData;
        String moduleId = "yourModuleIdUsedInYourModuleTags";
      
        ...
        xapplicationData = req.getSession().getAttribute(moduleId);
        ...
    }

  New code:
    import com.softwareag.xtools.xapplication.jsp.*;
    
    public void doGet(HttpServletRequest req, HttpServletResponse resp)
        throws IOException, ServletException
    {
        SessionContext xapplicationData;
      
        ...
        xapplicationData = ServletSessionContext.getSessionContext(req.getSession());
        ...
    }
    
  Note that the new code no longer depends on the module id.
    
o migrating Java API
  X-Application's Java API (i.e. the businessdocument package and the store package)
  remained almost unchanged.
  However, X-Application 3.1.2 includes a new version of Tamino Java API. To adjust your Java
  applications, please make sure that your CLASSPATH includes the file instrumentation.jar
  which is required by the new Tamino Java API.
  Note: the script %xapplication%/bin/xenv.cmd defines an environment variable XAPPLICATION_CP
  This variable includes the CLASSPATH required to run xapplication that use X-Application's
  Java API.

    
Changes
-------

* JSP tags
  o A new tag 'loopnavigation' was added to the existing tag library with the associated
    class 'LoopNavigationTag.java'. This allows the definition of a pagewise next/previous
    iteration over a multiplicity (occurrence).
  o Refactoring of the JSP package structure:
    - The package 'jsptaglib' was renamed to 'jsp'
    - The implementation of the JSP tags was moved into a sub-package 'taglib'.
  o ModuleCursor refactoring:
    - The class ModuleCursor was renamed to Page
    - It was moved to the business document package
    - It became an abstract class.
    - Its functionality of pagewise iteration was moved to the new classes
    (a) NodePage: iterates multiplicities
    (b) DocumentPage: iterates documents
  o position processing:
    - The :pos request to describe the index within a cursor was refactored. A position
      is not longer a simple index, now it is a position expression, a list of
      <cursor name>,<index> pairs.
    - The :goto request to describe the index within a document cursor was refactored. The
      format of the :goto parameter is:
    :goto(<cursor name>)=<index>
  o element action processing:
    - The value of a :elementaction to describe an action to be performed on a document node
      was refactored. The actions 'insert', 'remove', 'select' have an argument list with
      a postion expression and an index, e.g.
    :elementaction=insert(<cursor_name1>,<index1>,<cursor_name2>,<index2>,...;<index>)
    - Now, insert actions can be defined within a loop tag to add sub-node into an occurrence
      at any position.
  o Unit test refactoring
    Major parts of the jsptaglib package have been changed to allow unit tests for JSP tags.
    The most important changes are:
    o added a RequestContext class that represents the HTTP request parameters
    o added an ApplicationContext class that represents non-session specific state
    o renamed ModuleInstance to SessionContext (to match the naming conventions for
      RequestContext and ApplicationContext)
    o XBodyTag has been split into XTag and JspTag.
  o performace improvements
  o Error checking for tags, their attributes and request parameters has been improved.
    Examples:
    (1) Request parameters are case sensitive. :Pagesize will not longer be recognized
        as parameter. Only small letters are allowed for parameter names.
    (2) If more than one parameter with name ':pagesize' comes within a request, an exception
        will inform you about this design error.
    (3) To define Element action before the corresponding Loop was defined, will cause an
        error.
  o A JSP logging facility is added:
    The JSP logging facility is designed for application developers who want log the serveral
    activities of a web application. Therefore a new class 'TraceInfo' is added.
  o Exception handling refactoring :
    - Except of the RuntimeExceptions and IOExceptions, each exception will be encapsulated by an
      ExceptionContainer.
    - Each exception container gets a unique identifier.
    - Error messages of exception can be configure in a seperate file 'exceptions.xml'
      There a five possible types of exceptions :
                              * UserException
                              * MinorEnvironmentException
                              * MajorEnvironmentException
                              * DesignException
                              * ApplicationException
    - All the exceptions will be dispatched inside the class 'ExceptionContainer'.
      The aim is to help the user understanding occurring exceptions and to support him
      to solve the problem quicker.
        
* Java API
  o Switched to the latest version of Tamino API. This version depends on an additional
    jar file: prerequisites\lib\debug\instrumentation. Please check your classpath settings
    for IDEs, command scripts etc. and make sure to include this file.
  o The cursor interface has a method to request the pagesize of a cursor. The pagesize
    defines the number documents per request.
* X-Application Generator
  o I18N support was added, therefore several changes had to be made:
    o The name of the generated structure file had to be changed from
      structure_[DOCTYPENAME].xml to just structure.xml.
    o The encoding of the generated JSP pages is now UTF-8, the XSLT stylesheets where changed
      accordingly.
    o The response generated by the GuiServlet class is now written to a UTF-8 encoded PrintWriter
      rather than to a non-encoded ServletOutputStream.
    o The generated configuration files config.xml and web.xml are now UTF-8 encoded as well.
  o TSD schema choice tags are now supported, therefore the following changes where made:
    o The tags <choice> and <setchoice> are generated into the structure.xml file and interpreted
      by the XSLT stylesheets.
    o <heading> tags are used inside <loop> and <choice> tags as well, so that now the full path of
      every field is displayed in the generated pages.
  

=================================================================
(C) 2001 - 2002 Software AG, All rights reserved.
=================================================================