This document provides information about developing SAS Web applications. The SAS AppDev Studio Eclipse Plug-ins builds on the Eclipse Web Tools Platform (WTP). For information about the WTP, see the WTP Community Resources page (from the Eclipse Foundation).
The SAS Web Application Project provided by the SAS AppDev Studio Eclipse Plug-ins is built on top of the Dynamic Web Project provided by the Eclipse Web Tools Platform (WTP). Understanding how this is implemented will make it easier to understand how to develop SAS Web applications using the SAS AppDev Studio Eclipse Plug-ins and WTP features. Due to the relationship between the SAS Web Application Project and Dynamic Web Projects, here is a brief explanation of the WTP features involved.
All WTP based projects create a module of some type within the project. The supported module types include Utility JAR, Web Application, Enterprise Application, EBJ, and others. As you would expect, a Dynamic Web Project creates a Web Application module. Because of the one-to-one relationship between WTP projects and modules, it should not cause a problem to think of them as being the same. In various contexts within WTP, you might find either modules or projects referenced. For example, in the project Properties dialog box you will find a "J2EE Module Dependencies" page. In the context menu for a server in the Servers view you will find an "Add and Remove Projects" command, though the whole project is not added to the server, just its module.
The various types of WTP modules are distinguished from each other by the presence of one or more units of functionality, otherwise known as facets. Very importantly, a facet specifies a version of its functionality. For a number of facets, WTP uses this version to determine if a module can be run on a particular server. For example, the module for all WTP projects have at least the "Java" facet. The version of this facet determines the minimum Java version a server must supply before the module can run on that server. For Web Application modules, the only additional facet is the "Dynamic Web Module" facet, which specifies the version of the Servlet specifications the module requires. As you might expect, if you have a module that includes the "2.4" version of the "Dynamic Web Module" facet, you won't be able to run it on a server that only supports version "2.3" of the Servlet specifications, such as Tomcat 4.1.18.
To turn a Dynamic Web Project into a SAS Web Application Project, these additional pieces are required:
The SAS AppDev Studio Eclipse Plug-ins add these additional pieces to the project's module as part of a new facet named the "SAS Web Module with WIK" facet. SAS AppDev Studio 3.3 adds all three of these items. SAS AppDev Studio 3.2.2 and earlier only add the first two items (see the Standard SAS Filter and Servlet Declarations and Mappings Known Issue for details on addressing this third piece). The addition of these pieces was implemented as a facet to help ensure the SAS JAR files, the SAS WIK static content, and SAS web.xml entries stay in sync. This is necessary so that the Java script in the WIK static content works compatibly with the Java code in the SAS JAR files. In addition, it ensures that classes required by the SAS filters and servlets are available in the SAS JAR files. Unlike the "Dynamic Web Module" facet, the "SAS Web Module with WIK" facet does not impose any run time requirements that would affect which servers on which it can run.
The "SAS Web Module with WIK" facet adds the SAS
JAR files to the project by adding the SAS Repository to the Java
build path and adding the SAS JAR files as J2EE module dependencies.
This approach avoids physically copying the set of SAS JAR files into
every SAS Web Application Project and allows them to be easily
managed using the SAS Repository in the project. Because they are
listed as J2EE module dependencies, WTP will automatically
include the SAS JAR files in the Web application's WEB-INF/lib
folder when the module for a project is published to a server, or exported
as a WAR file. SAS AppDev Studio 3.3 adds the SAS Repository itself as the
J2EE module dependency. Since WTP 1.5.x and earlier did not support
adding the SAS Repository as a J2EE module dependency, SAS AppDev Studio
3.2.2 and earlier add each individual SAS JAR as a J2EE module dependency. This
achieves the desired result, but has side effects with respect to
the behavior of the J2EE Module Dependencies page in the
project's Properties dialog box. The side effects vary between
1.0x and 1.5.x versions of WTP, and thus between the 3.2 and 3.2.x
versions of SAS AppDev Studio.
Because SAS AppDev Studio 3.2 uses WTP 1.0.x, the J2EE Module Dependencies page will add an explicit entry to the project's Java build path for each manually added dependency. Only the presence of this explicit entry determines the state of the check box when you return to the J2EE Module Dependencies page. Because the SAS JAR files are added to the project's Java build path by the SAS Repository, and not individual explicit entries, the SAS JAR files are all unchecked in the list displayed by the J2EE Module Dependencies page. Unfortunately, changing the project's J2EE module dependencies incurs the risk of unintentionally removing all of the SAS JAR files, due to their not being checked. Checking the SAS JAR files does not help as this leads to duplicate classpath entry errors. See J2EE Module Dependencies Page May Unintentionally Remove the SAS JAR files from SAS Web Application Projects known issue for how to use the J2EE Module Dependencies page with SAS Web Application Projects in the SAS AppDev Studio 3.2 Eclipse Plug-ins.
Because SAS AppDev Studio 3.2.1 and 3.2.2 use WTP 1.5.x, the J2EE Module Dependencies page no longer adds an explicit entry to the project's Java build path. Instead the Web App Libraries classpath container will automatically pick up the J2EE module dependencies in the project, which includes the SAS JAR files. Because the J2EE Module Dependencies page uses the WebApp Libraries classpath container to determine the state of the check box, the SAS JAR files will be checked, and there is no risk of their unintentional removal. However, as a side effect of this new behavior in WTP 1.5.x, the SAS Repository does not display any JAR files in the Package Explorer or Project Explorer views for SAS Web Application Projects. See The SAS Repository library folder is always empty in SAS Web Application Projects known issue for details. Though the Web App Libraries contains the SAS JAR files and the SAS Repository is empty, you should still use the SAS Repository for managing the SAS JAR files.
Additional JAR files can be added to a SAS Web Application Project
using the WTP standard methods of copying the JAR file to the
project's WEB-INF\lib folder or using the J2EE Module
Dependencies page. If the desired JAR is available in the SAS
Version JAR Repository, then it can be added using the SAS
Repository in the project. However, the set of SAS JAR files added and
excluded by the "SAS Web Module with WIK" facet should
not be modified since these JAR files need to stay in sync with the
static content of the WIK. An exception to this rule applies to
SAS Web Application Projects created by the SAS AppDev Studio 3.2
Eclipse Plug-ins. There are two versions of Log4J available in the
SAS Version JAR Repository and the 1.2.9 version is included when
the 1.2.3 version is the one supported by SAS 9.1.3 SP4 Web
applications. The incorrect version is also included if you import
a Web application project from webAF 3.0. See the Specifying
the Correct Version of Log4J for SAS 9.1.3 SP4 Web Applications
known issue below for details about how to correct this. SAS
AppDev Studio 3.2.1 and later will include the correct
version of Log4J for new SAS Web Application Projects and projects
imported from webAF 3.0. However, this issue will still apply to
SAS Web Application Projects that are imported from a SAS AppDev Studio 3.2
workspace, if the error was not previously corrected.
In addition to the set of SAS JAR files, the "SAS Web Module with WIK" facet adds the WIK static content to the Dynamic Web Project. This is done by physically copying the files that comprise this content into the project. Though this approach makes it possible to edit the content, this content should not be modified. This approach was the only practical way to include the WIK static content in a Dynamic Web Project.
The final piece needed to turn a Dynamic Web Project into a SAS Web Application Project is the addition of the standard SAS filter and servlet web.xml entries. SAS AppDev Studio 3.3 automatically includes these web.xml entries as part of the "SAS Web Module with WIK" facet. SAS AppDev Studio 3.2.2 and earlier did not automatically include them as part of the facet. In these versions of SAS AppDev Studio, the only way to add these web.xml entries automatically is to include or add one of the Web application example templates to the project. If you are using SAS AppDev Studio 3.2.2 or earlier and want to develop a SAS Web application without using one of the example templates, see the Standard SAS Filter and Servlet Declarations and Mappings known issue for details about how to add them manually.
The J2EE Module Dependencies page in the project Properties dialog box can unintentionally remove the SAS JAR files from a SAS Web Application Project when changes are made to the dependencies. Unfortunately, their removal may not be readily apparent. So after making any change on the J2EE Module Dependencies page, you should close the Properties dialog box and then reopen it to J2EE Module Dependencies page and verify that the SAS JAR files are still listed. If any SAS JAR files are removed, then they all will be removed so you just need to check for the presence of any SAS JAR. If the SAS Repository JAR files have been removed, use the following procedure to restore them.
By changing the configuration of the SAS Repository, the J2EE module dependencies are brought back into sync with the SAS Repository, restoring them to the list. You should always use the SAS Repository Configuration dialog box when making changes to the set of SAS JAR files in the project.
The unintentional removal of the SAS JAR files is not an issue in SAS AppDev Studio 3.2.1 and later. In SAS AppDev Studio 3.2.1 and 3.2.2, new behavior in WTP 1.5.x causes the SAS JAR files to be checked, instead of unchecked. Thus, they are not at risk for removal. In SAS AppDev Studio 3.3, WTP 2.0.x fully supports adding the SAS Repository itself as a J2EE module dependency, avoiding the issue completely.
The SAS Version JAR Repository includes two versions of Log4J. The set of SAS JAR files that the SAS AppDev Studio 3.2 Eclipse Plug-ins includes for SAS Web Application Projects contains the wrong version of Log4J. For SAS 9.1.3 SP4 Web applications, the version should be 1.2.3 instead of 1.2.9. To correct this error, follow these steps:
The SAS AppDev Studio 3.2.1 and later include the correct version of Log4J, so this issue does not apply to new SAS Web Application Projects or webAF 3.0 projects that are imported. Projects imported from a SAS AppDev Studio 3.2 Eclipse Plug-ins workspace could still have the wrong version and might need to be updated.
The SAS Java Components require the following filter and servlet
declarations and mappings be included in the web.xml file for Web
applications. Prior to SAS AppDev Studio 3.3, if a Web application
example template is not added to a SAS Web Application Project,
then these entries must be added
manually. For Servlet 2.3 Web applications, these XML elements must
appear in the proper order. The <filter> and
<filter-mapping> elements should appear after any
<context-parameter> elements and before the <listener> and
<servlet> elements. The <servlet> and
<servlet-mapping> elements should appear after the <listener>
elements and before the <welcome-file-list> element. There are
other elements to be concerned with, but describing the full list here
is not practical. If you have Web Tools XML Validation enabled (which is the
default), then an error will occur if the elements are added out of
order.
<filter>
<filter-name>CharacterEncodingFilter</filter-name>
<filter-class>com.sas.servlet.filters.CharacterEncodingFilter</filter-class>
<init-param>
<param-name>encoding</param-name>
<param-value>UTF-8</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>CharacterEncodingFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
<servlet>
<servlet-name>MethodInvocationServlet</servlet-name>
<servlet-class>com.sas.servlet.util.MethodInvocationServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>SelectorServlet</servlet-name>
<servlet-class>com.sas.servlet.tbeans.dataselectors.SelectorServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>StreamContentServlet</servlet-name>
<servlet-class>com.sas.servlet.util.StreamContentServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>VisualDataExplorerServlet</servlet-name>
<servlet-class>com.sas.servlet.util.VisualDataExplorerServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>Model2ExampleControllerServlet</servlet-name>
<servlet-class>servlets.Model2ExampleControllerServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>MethodInvocationServlet</servlet-name>
<url-pattern>/MethodInvocationServlet</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>SelectorServlet</servlet-name>
<url-pattern>/SelectorServlet</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>StreamContentServlet</servlet-name>
<url-pattern>/StreamContentServlet</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>VisualDataExplorerServlet</servlet-name>
<url-pattern>/VisualDataExplorerServlet</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>Model2ExampleControllerServlet</servlet-name>
<url-pattern>/Model2Example</url-pattern>
</servlet-mapping>
Because SAS AppDev Studio 3.2.1 and 3.2.2 build
upon the 1.5.x version of WTP, an implementation detail of this
version requires that the SAS Repository library folder be empty.
Dynamic Web Application projects, and thus SAS Web Application
Projects, will contain a library folder named Web App Libraries.
This library folder is automatically populated with JAR files placed in
the project's WEB-INF/lib folder as well as JAR files
listed as J2EE module dependencies in the project's properties.
The later is a change from the WTP version 1.0.x behavior, which
only included WEB-INF/lib JAR files. Because the SAS
Repository JAR files are added to a SAS Web Application Project as J2EE
module dependencies, they will appear in the Web App Libraries
library folder. Since they appear there, they can not also appear
in the SAS Repository library folder or duplicate classpath entry
errors will result.
Even though the SAS Repository library folder does not display the SAS JAR files, configuring the SAS Repository is still the correct way to manage the SAS JAR files. You should not try to manage the SAS JAR files using the J2EE Module Dependencies page in the project's Properties dialog box, even though you will see them listed there.
Since WTP 2.0.x fully supports classpath containers, such as the SAS Repository, as J2EE module dependencies, this issue does not apply to SAS AppDev Studio 3.3. The SAS JARs again appear under the SAS Repository library folder and not in the Web App Libraries library folder.