Upgrading Page Flows

This topic gives more detail about upgrade changes noted for page flows.

For a more complete list of changes affecting applications upgraded from version 8.1, see Changes During Upgrade from WebLogic Workshop 8.1 to Version 10.x.

Changes When Upgrading from Version 8.1 NetUI JSP Tags

When upgrading using upgrade tools, you'll have the option to choose to replace your version 8.1 NetUI JSP tags with the version 10.x NetUI JSP tags, which provide enhanced functionality over the version 8.1 tags. (The NetUI tags are the default for new web projects in Workshop version 10.x.) The default behavior is not to replace version 8.1 tags with current NetUI tags. Instead, by default version 8.1 tags are upgraded to a version of the 8.1 tags that is compatible with a version 10.x server.

Note: A JSP page can use a combination of compatible 8.1 tags and 10.x tags. However, this is only supported when the combination is due to an upgrade outcome in which some version 8.1 tags have no 10.x counterparts.

As you might imagine, the decision you make about the tags will have a broad impact on the JSP portion of your application. Before choosing, consider the following:

• In general, if you want to use the current tags, you're likely to find that migrating to them is best done as a two-step process: upgrading to the compatible 8.1 tags, then migrating to the current tags. This gives you an opportunity to ensure that your upgraded application runs on a version 10.x server before migrating to the current technology. Note, too, that you can later migrate portions of your application to the current model as you revise your application, creating new JSP pages or upgrading existing ones.
• If your application is in maintenance mode, consider not replacing version 8.1 tag with current tags. Upgrading to the compatible 8.1 tags (the default behavior) is likely to get your version 10.x application up and running more quickly.
• If your application is still in development, consider replacing version 8.1 tags with current tags. You're likely to find that the advantages of the enhanced 10.x tags are worth the effort of migrating fully.

Tag Changes

If you choose to replace version 8.1 tags with 10.x tags during application upgrade, many of the version 8.1 tags will be replaced with easily identifiable 10.x counterparts. There will be exceptions to this predictability, as the following table describes.

Attribute Changes

During upgrade some JSP tag attributes may be migrated to new attributes, or simply removed. The following table describes possible changes.

Upgrade Sets the Default Expression Language to a Backward-Compatible Version

When upgrading an application, you'll be prompted to upgrade version 8.1 NetUI JSP tags. Whether or not you choose to upgrade, the default expression language in your upgraded application will be a backward-compatible version, rather than the version used for new applications. This is because the backward-compatible version is more permissive, allowing you to continue with your existing code until you are ready to upgrade fully. If and when you choose to upgrade fully to the current JSP tag technologies, you should change the default expression language to the version that supports the current tags.

If you add JSP tags to your pages, they will use version 10.x of the expression language. Until that time, you should continue to use the backward-compatible expression language as the default. See Changing the Default Expression Language Used by JSP Tags for more information.

Note: In general, you should regard the version 8.1 NetUI tags as deprecated; new code should use the version 10.x NetUI JSP tags.

Changing the Default Expression Language Used by JSP Tags

When you have fully upgraded your JSP pages so that they use the current JSP tags, you should change the default expression language from the backward-compatible version to the version 10.x.

Note: Before making this change, you should be aware of code changes that might be required.

You can change the default expression language by editing the beehive-netui-config.xml file in your project. You'll find that file at a path such as the following:

WORKSPACE_HOME\PROJECT_HOME\web\WEB-INF\beehive-netui-config.xml

Possible settings for default language include netuiel (for the JSP 2.0 expression language) and compat-netuiel (for the version 8.1 NetUI expression language. In other words, to change to the default to the JSP 2.0 expression language, change the file so that it includes the following:

<expression-languages>
    <default-language>netuiel</default-language>
    ....
</expression-languages>

Changing Code to Support the Expression Language in Version 10.x NetUI JSP Tags

If you choose to upgrade version 8.1 NetUI JSP tags to version 10.x NetUI JSP tags, changes to your JSP code will include expression changes to support the expression language used by the current tags. The following describes changes made by the tools during upgrade, as well as changes you might need to make to your own non-JSP code.

Expression Changes

The following changes are made to expressions during upgrade.

• Use of dataSource attributes is changed from dataSource="{actionForm.name}" to dataSource="actionForm.name".
• Expressions of the form {expression} are changed to ${expression} (except for the dataSource attribute).
• Version 8.1 binding contexts are changed according to the following table:
  
  

  	8.1 Binding Context 10.x Implicit Object Comment url param Changed to the JSP 2.0 implicit object name request requestScope Changed to the JSP 2.0 implicit object name application applicationScope Changed to the JSP 2.0 implicit object name session sessionScope Changed to the JSP 2.0 implicit object name pageContext pageScope Changed to the JSP 2.0 implicit object name actionForm actionForm   pageInput pageInput   container container   pageFlow pageFlow   globalApp globalApp   bundle bundle     sharedFlow This is a new bindiing context.   backing This is a new bindiing context used with JavaServer Faces.

Changes Needed to Bind to Public Data Members

If you upgrade version 8.1 NetUI JSP tags to version 10.x NetUI JSP tags, you may need to change how data held by public members is exposed to tags for binding. Whereas version 8.1 supported binding expression code to public fields, in version 10.x expressions can only bind to public accessors.

In other words, although upgrade tools will upgrade the expression language syntax used in JSP tags, they will of course not add accessors to classes where needed. For a full upgrade to current JSP tags, you must manually add get* and set* accessors where public fields were used.

Reserved Words Can Not Be Used as Identifiers

The JSP 2.0 expression language reserves the following words; your code should not use them as identifiers.

and    eq    gt    true    instanceof

or    ne    le    false    empty

not    lt     ge     null     div     mod

Note that you can inadvertently use a reserved word by including that word in the name of an accessor designed to expose a property to expression language code. For example, the following code would be designed to expose an empty property:

public String empty;
public String getEmpty() {return empty;}

In the JSP page, of course, this would result in using "empty," which is a reserved word, as a property name:

<netui:content value=?${pageFlow.empty}? defaultValue=?NO VALUE?/>

Instead, trying using a naming scheme that results in a method name such as "getEmptyVal", then bind to them with pageFlow.emptyVal.

For more information about the expression language, see Expression Language in the J2EE 1.4 tutorial.

Form Classes Must Include a Default Constructor

Unlike version 8.1, version 10.x enforces a requirement that forms used in page flow (such as those which extended the now-deprecated FormData class) must have a default constructor.

You can work around this change by adding a default constructor after upgrading your code.

Updating XQuery Use to Support Upgraded XQuery Implementation

In version 8.1, XMLBeans supported XQuery Working Draft 16; Working Draft 23 is used in version 10.x. Upgrade tools will generally update XMLBeans code that executes XQuery expressions, but not code in JSP files. You will need to make the required change manually for code based on the older implementation to work.

For more information, see Updating XQuery Use to Support Upgraded XQuery Implementation.

Fixing Package Names That are Not Upgraded in Page Flow Controller Files

In a page flow Controller file, when a type name is fully-qualified outside a type import, the type's package may not be upgraded to the package used in version 10.x. For example, in the following after-upgrade code, note that the package for Forward has not been upgraded from com.bea.wlw.netui.pageflow to org.apache.beehive.netui.pageflow.

/**
 * @jpf:action
 * @jpf:forward name="begin" path="Begin.jsp"
 */
@Jpf.Action(forwards = {
    @Jpf.Forward(name = "begin",
                 path = "Begin.jsp")
})
public Forward begin()
{
    return new com.bea.wlw.netui.pageflow.Forward("begin");
}

The errors will be highlighted in source code. You can make fixes by using the Workshop quick fix feature to replace the type with the correct type of the same name. You can also search and replace to fix.

Custom Tags That Extend NetUI Tags are Not Supported

If you created custom JSP tags in version 8.1 by extending NetUI tags, your tags will not be upgraded by Workshop tools. Extending NetUI tags was not supported. Note that if you elected not to migrate NetUI tags to current tags, your tags may build within the application, but may not work as expected.

Likewise, extending JSP tags in version 10.x is not supported.

Updating Code to Reflect Changes in State Tracking API

In version 10.x, several methods in the NetUI API have been changed so that, under certain circumstances, they return IllegalStateException rather than null. This is an improvement over the version 8.1 API, in which null was returned regardless of whether the requested return value was actually null or simply unknown because it wasn't being tracked.

You can avoid handling IllegalStateException by overriding the alwaysTrackPreviousAction method in your page flow controller so that that method returns true. Note that this might negatively impact the performance of your application. Here's how it would look:

protected boolean alwaysTrackPreviousAction()
{
    return true;
}

The following is a list of affected methods:

• getPreviousActionURI
• getPreviousActionInfo
• getCurrentPageInfo
• getPreviousPageInfo
• getPreviousFormBean
• getCurrentForwardPath
• getPreviousForwardPath

The following lists detailed circumstances surrounding the change:

• This change is only relevant if the current page flow does not use a @jpf:forward with a return-to="previousAction" attribute.
• If alwaysTrackPreviousAction is not overridden to return true, the version 10.x methods will return java.lang.IllegalStateException.
• If alwaysTrackPreviousAction is overridden to return true, then the version 10.x methods will either return the requested value or null if the value is in fact null.

Replacing Callback-Enabled Controls Used in a Page Flow

In version 10.x custom controls used from a page flow can't receive external callbacks. In version 8.1, you could write a custom control that received callbacks from controls nested within it, such as service controls. By exposing a polling interface from your custom control, your page flow code could then retrieve responses received from the callbacks. This functionality is not supported in version 10.x.

In upgraded code, you can substitute for this functionality by replacing your custom control with a web service. For more information on the version 8.1 feature and suggested version 10.x workarounds, see Providing Support for Callbacks from a Page Flow.

Ensuring Assembly of Controls Used from a JSP Page

In version 10.x, some controls require a compile-time assembly process that generates artifacts needed by the runtime. These controls include the service control, EJB control, and timer control.

This assembly process is only triggered for these controls when they're referenced within a Java file — effectively excluding controls that are referenced only from JSP pages. In upgraded code, you can work around this change from version 8.1 by referencing the control from a Java file.

The best place for this reference is the page flow controller file; if there's no controller in your application, you can add the reference to another Java file that's compiled with the application. You do this by adding an org.apache.beehive.controls.api.bean.ControlReferences annotation that names the control class used in the JSP page. Here's an example that references a single control:

@ControlReferences(value={mycontrols.MyServiceControl.class})
public class Controller extends PageFlowController {
    ...
}

Resolving Name Conflicts Between Jpf.Forward and validationErrorForward

Version 8.1 allowed the jpf:validation-error-forward and jpf:forward annotations to have the same value for their name attributes; this is not allowed in version 10.x. For example, you might have had version 8.1 code such as the following, in which "failure" is used twice as a name attribute value:

/**
 * @jpf:action
 * @jpf:forward name="success" return-action="addProfileDone"
 * @jpf:forward name="failure" path="addClient.jsp"
 * @jpf:validation-error-forward name="failure" return-to="currentPage"
 */
protected Forward addClientProfile(MaintainIndividualProfileForm form)
{
    ...
}

The upgraded counterparts to this code (in the Jpf.Forward annotation and the Jpf.Action validationErrorForward attribute) will generate a build error in version 10.x. You can work around this change by changing one or both of the attribute values so they're not the same.

Upgrade Changes for Co-Location in Page Flows

Version 8.1 supported a project hierarchy in which the Controller file (Controller.jpf) and JSP files could be put into the same directory. This is not supported in version 10.x.

For example, during upgrade the following hierarchy change will occur for upgraded page flows:

Version 8.1

webapp/
    Controller.jpf
    index.jsp

Version 10.x (after upgrade)

webapp
    src
        Controller.java
    web
        index.jsp

The version 8.1 style is referred to as co-location. In version 10.x (including for upgraded applications), JAVA source files and JSPs are kept in different directories. Note that if you create a new page flow called myPageFlow, it would feature two parallel directories called myPageFlow — one for JAVA source code and one for the JSPs. Here's a simplified example:

webapp
    src
        myPageFlow
            myPageFlowController.java
        Controller.java
    WebContent
        index.jsp
        myPageFlow
            index.jsp
            page1.jsp
            other JSPs

Fixing Erroneous IDE Error for Variable in an HTML Start Tag

The version 9. 2 IDE incorrectly displays an error for code in which a variable declaration is made in an HTML start tag; the code is actually valid at run time. For example, in the following anchor tag the <%=s%> code using the String variable is flagged by the IDE as unresolved, but is actually valid:

<a href="<%! String s="test"; %><%=s%>">Test</a>

This also applies to WebLogic Portal tags that set Java variables, such as <render:getJspUri> and <render:getSkinPath>.

You can work around this in code upgraded from version 8.1 by moving the variable declaration to a line outside a start tag, as follows:

<%! String s="test"; %>
<a href="<%=s%>">Test</a>

Import and Use of com.bea.wlw.netui.util.XMLString are Not Supported and Will Not be Upgraded

This XMLString class (not to be confused with XMLBeans' org.apache.xmlbeans.XmlString) is not included in version 10.x. Upgraded code that imports the type will generate compilation errors. In version 8.1 this class was used in conjunction with the XScript expression language, which has been removed from version 10.x.

When upgrading web applications, the Page Flow Controllers source folder may revert to the default location in some cases

Certain version 9.2 web projects with the Beehive NetUI facet may not retain the value of the Associated Files Model settings. Specifically, if such a project has more than one source folder, and the Page Flow Controllers property panel has been set to a source folder other than the default, this value will revert to the default when the project is upgraded.

In a project that has both the Beehive NetUI facet and the JSF facet, the same situation may occur for the Project > Properties > Associated Files Model > JSF Backing Files property.

To change the value, select Project > Properties > Associated Files Model > Page Flow Controllers and select the source folder of interest.

Related Topics

Changes During Upgrade from WebLogic Workshop 8.1 to Version 10.x