Resources

SAS® AppDev Studio 3.0 Developer's Site

WebLogic Deployment Information

The BEA WebLogic Server provides an industrial-strength set of services for building e-commerce applications using the Java 2 Enterprise Edition (J2EE) standards, including Enterprise JavaBeans (EJB) components. For more information about the BEA WebLogic Server, see www.beasys.com.

This document covers the BEA WebLogic Server 8.1, the BEA WebLogic Server 8.1 SP1, and the BEA WebLogic Server 8.1 SP2. Also, it only addresses deployment to managed servers with the admin server running in production mode and using WebLogic's Administration Console for management. This approach was chosen as the preferred approach for production deployment. The information below can be applied to other approaches, such as the use of batch scripts, if desired.

In the information below, the following topics are covered:

Installation Issues

If you are using WebLogic 8.1 SP1, you should obtain the CR112484 patch from WebLogic Support. Without this patch, a regression in SP1 will cause JSP files that make use of certain tag libraries to fail to compile. Tag libraries that suffer from this regression include both the SAS Taglib and TBeans (Version 2) and the SAS Taglib and TBeans (Version 3) tag libraries.

If you are using WebLogic 8.1 SP1 on Windows, there is an error in the startNodeManager.cmd file found in the <BEA home>\weblogic81\server\bin directory. The quotes should be removed from the line in this file that contains:

set NODEMGR_HOME="%WL_HOME%\common\nodemanager"

The updated line should be:

set NODEMGR_HOME=%WL_HOME%\common\nodemanager

This correction to WebLogic 8.1 SP1 allows the Node Manager home directory to be the intended value of <BEA home>\weblogic81\common\nodemanager, which is consistent with WebLogic 8.1 and WebLogic 8.1 SP2 (which includes this correction). Without this correction to WebLogic 8.1 SP1, the Node Manager home directory will be <BEA home>\weblogic81\server\bin instead.

Important Note: The information in the following sections assumes that you have made this correction to the Node Manager home directory if using WebLogic 8.1 SP1.

Deployment Strategies

The discussion that follows covers only deployment using the Deployment Assistant in WebLogic's Administration Console. Other techniques, such as using Apache Ant scripts with custom WebLogic tasks or the deployment API are not covered. You can start the Deployment Assistant by clicking on Web Application Modules in the WebLogic Server Home page of the Administration Console, or by selecting Web Application Modules under Deployments in the tree on the left. On the page that appears, click Deploy a new Web Application Module to start the Deployment Assistant.

The Deployment Assistant uses the name of the source directory or WAR file, without the ".war" extension, as the context name under which the Web application will be served. This name is also used as the default name of the Web application deployment, which is specified in the Name text field on the last page of the Deployment Assistant. This is the page with the Deploy button. For simplification, the sections below assume that you have used the default deployment name and that it remains the same as the context name.

In webAF, the WAR file that is created for a Web application project will use the same name as the project, plus the ".war" extension. Thus, if you plan to deploy a WAR file, try to use the desired context name as the name the webAF Web application project. If this is not practical, or if you plan to deploy the source directory, you can set the context name by copying the WAR file or source directory to a convenient deployment directory and then renaming the WAR file or source directory. If you are running your domain's admin server in production mode, the applications directory under your domain's home directory can be a convenient location from which to deploy to the managed servers.

If you plan to deploy a WAR file, you can also use the Deployment Assistant to upload the WAR file. You can use the link provided on the first page of the Deployment Assistant. The WAR file will be placed in the admin server's upload subdirectory under the domain's home directory. On Windows, for a domain created using the WebLogic defaults, the domain home directories would be the following:

WebLogic 8.1: C:\bea\user_projects\mydomain\myserver\upload
WebLogic 8.1 SP1 and SP2: C:\bea\user_projects\domains\mydomain\myserver\upload

Finally, note that a number of SAS components are not serializable. If after you deploy a Web application, the Web application stores one of these components as an attribute in an HTTP session, a warning will be logged by the Http Session SubSystem with a message that would look similar to the following:

    Web application: ServletContext(id=19374552,name=JDBCApp,con
    text-path=/JDBCApp) tried to place a non-serializable attrib
    ute: sas_actionProvider into the session: 11TUQGBCsbYfHssDbn
    vCVIHnq3cp9nPLSAMhra0QMFCI6GG6Mb8X!-1739164707!1073681236416
    . This attribute will be lost upon redeployment. This messag
    e is logged only once per session.

You can view this log by navigating to your domain, and then clicking the View domain log link found at the lower left corner of the page.

Because the session attribute is not serializable, or it contains an object which is not serializable, it will not be able to migrate to the other servers in a cluster. As a result, the presence of this message is an indication that the clustering features of WebLogic will not be available to this Web application. This is in addition to the session attribute being lost upon redeployment, which applies to server restarts as well.

In addition to deploying the Web application, there might be additional files or resources that need to be deployed to the WebLogic server in support of the Web application. You should review each Web application to determine what external dependencies exist and how to address them for deployment. Examples of such files or resources include JAAS configuration files and Java policy file permissions. Such dependencies are typically viewable in webAF Web application projects by executing File [arrow] Project Properties and selecting the Startup panel. Then examining the contents of the field named For this project, pass additional arguments to the Java interpreter. Start-up System properties defined there might reference additional files required by the Web application.

Serving the WAR File or a Source Directory

WebLogic 8.1, WebLogic 8.1 SP1, and WebLogic 8.1 SP2 all support serving Web applications from the WAR files and from source directories. If you deploy a WAR file, you can serve the Web application directly from the WAR file by choosing the nostage mode of deployment.

When you use the Deployment Assistant in WebLogic's Administration Console, select the nostage mode of deployment on the Review your choices and deploy page of the wizard. Under the Source Accessibility section, choose the I will make the Web Application module accessible from the following location: option. The text field below that option should already contain the path to the WAR file.

If you are deploying a Web application source directory, you can serve it directly from the directory by also choosing the nostage mode of deployment. After choosing the source directory to deploy in the Deployment Assistant, this is accomplished the same way as described above for WAR files.

The alternative to using nostage mode is stage mode. In stage mode, the content of the Web application is copied to a staging directory, from which it is served. On the Review your choices and deploy page of the wizard, select the Copy this Web Application module onto every target for me option. If you are deploying a WAR file, its contents will be expanded when the server copies it to the staging directory. The primary purpose for using stage mode is to make a local copy of the Web application content when the WAR file or source directory is on a different system.

Updating WebLogic Managed Server Settings

Specifying JVM Options and Start-up System Properties

To set JVM options and start-up System properties, use the Administration Console. Navigate to the managed server that you want to configure. Select Configure from the upper row of tabs, then select Remote Start from the lower row of tabs. Specify the JVM options and start-up System properties in the Arguments text field, and then click Apply. If the managed server is already running, you will have to restart it to have the new settings to take effect.

If you are deploying the Web application from a webAF project, you can find the JVM options and start-up System properties being used by that project by executing File [arrow] Project Properties and selecting the Startup tab. The field named For this project, pass additional arguments to the Java interpreter contains the JVM options and start-up System properties specific to that project.

For Web applications that access back-end or other servers, there will likely be System properties that define host names and port numbers for those servers, such as "-Dsas.rmi.host=<computer name>". These System properties are typically referenced in security permissions found in the policy file to make it easier configure and require less editing during deployment. As a result, most of the JVM options and start-up System properties will need to be included in the managed server's Arguments text field. Where you find a webAF supported macro, such as "${ProjectLocation}" and "${WebAppLocation}", manually replace them with appropriate values.

Specifying JVM Runtime Permissions

You can augment or replace the default JVM run-time permissions by using the java.security.policy System property to specify the path to a policy file. This System property is unique in that it can use "=" or "==" to indicate whether the policy file specified should append to, or replace the default permissions. If you use the "=", then the permissions in the specified policy file are appended to the default permissions. If you use the "==", then the permissions in the specified policy file replace the default permissions.

In addition to adding a java.security.policy System property as described in the previous section, the Administration Console provides you with a way to directly specify the policy file. Navigate to the managed server that you want to configure. Select Configure from the upper row of tabs, then select Remote Start from the lower row of tabs. Specify the path for the policy file in the Security Policy File text field, and click Apply. Specifying the policy file in this way causes the java.security.policy System property to be added automatically using "==" form of declaration. If the managed server is already running, you will have to restart it to have the new settings take effect.

To avoid side effects, the WebLogic weblogic.policy file found in <BEA home>\weblogic81\server\lib should not be modified to add permissions intended for node managed servers. Instead, make a copy of this file in your domain's home directory, or other suitable location, and use that as the policy file for the managed server. You can have a separate policy file for each managed server, or have multiple managed servers share a policy file, if appropriate.

With WebLogic, you will likely need two grant blocks for each Web application. One block will specify a codeBase that, in a simplified sense, covers Web application classes that are found in the WEB-INF/classes directory. The other block will specify a codeBase that, also in a simplified sense, covers Web application classes that are found in the JAR files in the WEB-INF/lib directory and compiled JSP files.

In many cases, a permission required by a Web application will need to appear in both of its grant blocks, although some may not. However, trying to accurately identify which permissions do not need to be duplicated is probably not worth the effort. Keeping the same set of permissions in both grant blocks will simplify maintaining these permissions.

For a managed server, the codeBase value for the grant block that covers JAR files will be deterministic with respect to the BEA installation directory, managed server's name, the name of the Web application's WAR file or source directory, and the Web application's deployment name. As stated in the Deployment Strategies section, the default value of the deployment name is assumed to be used so that it will be the same as the Web application's WAR file or source directory name.

For the grant block that covers JAR files, you can use the following parameterized version:

// Note: In your file, combine the following two lines into a single line.
grant codeBase "file:${bea.home}/weblogic81/common/nodemanager/
        ${server.name}/.wlnotdelete/extract/${server.name}_${myapp.name}_${myapp.name}/-"
{
...
};

The codeBase value above requires three System properties, bea.home, server.name, and myapp.name, to specify the BEA home directory, the server name, and the Web application name, respectively. For multiple Web applications, you would need to substitute a unique System property name for the myapp.name parameter name for each Web application. The System property name that you chose must also be substituted where it appears in any permissions given below. You should also note that for this grant block to work in WebLogic 8.1 SP1, you must apply the correction that is described in the Installation Issues section.

For a managed server, the codeBase value for the grant block that covers classes in the WEB-INF/classes directory will vary depending on whether you choose to deploy a WAR file or a source directory, and whether you choose to deploy using stage mode or nostage mode. For nostage mode, the codeBase value should be the path to the WAR file or the source directory. For a source directory, "/-" should be appended so that all of the subdirectories are included.

If you use the domain's application directory as the deployment directory, then the following two parameterized grant blocks could be used for WAR file and source directory deployments, respectively:

// WAR file deployed in "nostage" mode
grant codeBase "file:${domain.home}/applications/${myapp.name}.war"
{
    ...
}

// Source directory deployed in "nostage" mode
grant codeBase "file:${domain.home}/applications/${myapp.name}/-"
{
    ...
}

The codeBase value requires one additional System property, domain.home, to specify the domain's home directory. The same Web application name System property that was used for the first grant block should be used for the remaining parameter in the codeBase value.

For staged mode deployment, the codeBase value for the grant block that covers classes in WEB-INF/classes is also deterministic based on the same three parameters used in the first grant block. You can use one of the following two grant blocks for WAR file or source directory deployment, respectively, provided the servers' Deployment staging directory is still the default value of ./<server name>/stage:

// WAR file deployed in "stage" mode
// Note: In your file, combine the following two lines into a single line.
grant codeBase "file:${bea.home}/weblogic81/common/nodemanager/
        ${server.name}/stage/${myapp.name}/${myapp.name}.war/-"
{
    ...
}

// Source directory deployed in "stage" mode
// Note: In your file, combine the following two lines into a single line.
grant codeBase "file:${bea.home}/weblogic81/common/nodemanager/
        ${server.name}/stage/${myapp.name}/${myapp.name}/-"
{
    ...
}

When deploying multiple Web applications, you should substitute the same System property name in this grant block that was substituted for myapp.name in the first grant block.

If you are deploying a Web application from a webAF Web application project that uses a security manager, then there should be a java.webapp.policy file in the home directory of the project. This policy file is appended to the JVM's default policy file when running webAF's integrated Java web server. The top portion of this file contains permissions related to the Java web server, which is a version of Jakarta Tomcat. The bottom portion contains permissions related to the Web application, or possibly multiple Web applications. These Web application related permissions should be copied to appropriate grant blocks in the policy file for the managed server. Any System properties that the permission depend on will need to be added to the managed server's start-up parameters as described in the Specifying JVM Options and Start-up System Properties section.

Note that if you have installed the SAS AppDev Studio Java Components 3.1.2 Update, the java.webapp.policy file was updated to include some additional permissions. To be more restrictive, some of these permissions are granted to specific jars within the Web application. In the policy file for WebLogic, it isn't practical to grant permissions to specific jars within a Web application. Instead, include these permissions with the others in both grant blocks for Web applications built using the AppDev Studio 3.1.2 Update.

If you use SAS Foundation Services to access an Open Metadata Repository, as well as certain other operations, then you will need to add some run-time permissions, even if a security manager is not enabled. These permissions are the following:

    permission com.sas.services.user.CredentialPermission "readCredential", "ReadCredential";
    permission com.sas.services.user.UserContextPermission "*", "read";

The above run-time permissions should be in included in both of the grant blocks that you add for a Web application. In a SAS AppDev Studio installation, these permissions can be found in the java.app.policy file in the webAF\resources directory.

Enabling the Security Manager

To enable a security manager, include a java.security.manager System property on the Java start-up command. If the start-up command does not specify a security manager class, then the default security manager class is used.

To add this System property, select the managed server and then select the Remote Start tab. Add the java.security.manager System property to the Arguments: field and then click Apply.

When you enable a security manager, you will need to add various permissions to avoid security exceptions in some typical operations. In the grant blocks and the permissions that follow, where possible, the same System properties that were described in the Specifying JVM Runtime Permissions section will be used.

Note that the grant blocks and permissions needed by WebLogic 8.1 and WebLogic 8.1 SP1 are the same. Due to changes in the default weblogic.policy file, the grant blocks and permissions needed by WebLogic 8.1 SP2 are different.

To allow node managed servers to be started with a security manager in WebLogic 8.1 and 8.1 SP1, you can add, if not already present, the following grant block. This grant block is not needed in 8.1 SP2.

// Needed by WebLogic 8.1 and 8.1 SP1 to start a managed server if the security manager is enabled.
grant codeBase "file:${bea.home}/weblogic81/common/nodemanager/lib" {
    // Also include this permission in each Web application grant block
    permission java.lang.RuntimePermission "weblogic.kernelPermission";
};

The permission above should also be included within both grant blocks for each Web application to allow for session creation and other operations. This applies to WebLogic 8.1, 8.1 SP1 and 8.1 SP2.

To avoid a security exception related to WebLogic logging in WebLogic 8.1 and 8.1 SP1, you can add the following permission to both grant blocks for each Web application. It is not needed in 8.1 SP2.

    // Needed by WebLogic 8.1 and 8.1 SP1 to avoid an internal logging related exception
    permission java.net.SocketPermission "${host.name}", "resolve";

Note that this permission assumes that you have defined a System property named host.name that specifies the system's host name. Using "localhost" for the host name is not sufficient.

To avoid security exceptions while compiling JSP files at run-time, you can add the appropriate grant block below to give needed privileges to the tools.jar file.

// Needed by WebLogic 8.1 and 8.1 SP1, if a web application compiles JSP files at run-time
grant codeBase "file:${java.home}/../lib/tools.jar" {
    permission java.io.FilePermission "${java.home}${/}-", "read";
    permission java.io.FilePermission "${domain.home}${/}-", "read, write";
};
// Needed by WebLogic 8.1 SP2, if a web application compiles JSP files at run-tine
grant codeBase "file:${java.home}/../lib/tools.jar" {
    permission java.util.PropertyPermission "sun.boot.class.path", "read";
    permission java.util.PropertyPermission "java.ext.dirs", "read";
    permission java.io.FilePermission "${java.home}${/}-", "read";
    permission java.io.FilePermission "${bea.home}${/}weblogic81${/}-", "read";
    permission java.io.FilePermission "${bea.home}${/}weblogic81${/}common${/}nodemanager${/}-", "write";
    permission java.io.FilePermission "${domain.home}${/}-", "read";
};

In addition, the appropriate set of permissions below can be added to both grant blocks for each Web application that needs to compile JSP files at run-time:

// Needed by WebLogic 8.1 and 8.1 SP1, if a web application compiles JSP files at run-time
    permission java.io.FilePermission "${domain.home}${/}applications${/}-", "read";
    // Note: In your file, combine the following three lines into a single line.
    permission java.io.FilePermission "${bea.home}${/}weblogic81${/}common${/}
            nodemanager${/}${server.name}${/}.wlnotdelete${/}extract${/}
            ${server.name}_${myapp.name}_${myapp.name}${/}jsp_servlet${/}-", "delete";

    permission java.io.FilePermission "${java.home}${/}lib${/}-", "read";
    permission java.io.FilePermission "${java.home}${/}classes", "read";
    permission java.io.FilePermission "${java.home}${/}classes${/}-", "read";
    permission java.io.FilePermission "${java.home}${/}..${/}lib${/}tools.jar", "read";
    permission java.io.FilePermission "http:${/}-", "read";
    permission java.io.FilePermission ".${/}http:${/}-", "read";
// Needed by WebLogic 8.1 SP2, if a web application compiles JSP files at run-time
    permission java.util.PropertyPermission "file.encoding", "read";
    permission java.util.PropertyPermission "java.class.path", "read";
    permission java.util.PropertyPermission "java.ext.dirs", "read";
    permission java.util.PropertyPermission "java.library.path", "read";
    permission java.util.PropertyPermission "sun.boot.class.path", "read";
    permission java.util.PropertyPermission "user.dir", "read";
    permission java.util.PropertyPermission "weblogic.*", "read";

    permission java.lang.RuntimePermission "accessClassInPackage.sun.io";
    permission java.lang.RuntimePermission "createClassLoader";
    permission java.lang.RuntimePermission "weblogic.kernelPermission";

    permission java.io.FilePermission "${domain.home}${/}applications${/}-", "read";
    permission java.io.FilePermission "${bea.home}${/}weblogic81${/}server${/}lib${/}-", "read";
    permission java.io.FilePermission "${bea.home}${/}weblogic81${/}common${/}nodemanager", "read";
    permission java.io.FilePermission "${bea.home}${/}weblogic81${/}common${/}nodemanager${/}-", "read";
    // Note: In your file, combine the following three lines into a single line.
    permission java.io.FilePermission "${bea.home}${/}weblogic81${/}common${/}
            nodemanager${/}${server.name}${/}.wlnotdelete${/}extract${/}
            ${server.name}_${jdbcapp.name}_${jdbcapp.name}${/}-", "write, delete";
    permission java.io.FilePermission "${bea.home}${/}weblogic81${/}common${/}perf${/}java${/}-", "read";

    permission java.io.FilePermission "${java.home}${/}lib${/}-", "read";
    permission java.io.FilePermission "${java.home}${/}classes", "read";
    permission java.io.FilePermission "${java.home}${/}classes${/}-", "read";
    permission java.io.FilePermission "${java.home}${/}..${/}lib${/}tools.jar", "read";
    permission java.io.FilePermission "http:${/}-", "read";
    permission java.io.FilePermission ".${/}http:${/}-", "read";

The java.home System property is created automatically by the JVM, so it does not need to be included in your configuration. If you are serving multiple Web applications, change the occurrences of myapp.name in the permissions above to be the unique System property name that is being used by the respective Web applications.

If the Web application uses SAS Foundation Services and requires the use of a JAAS login configuration, typically found in a login.config file, you will need to include the following permissions in both grant blocks for that Web application.

// Needed by WebLogic 8.1, 8.1 SP1, 8.1 SP2, if a web application uses SAS Foundation
// Services and requires a JAAS login configuration
    permission java.security.SecurityPermission "getProperty.policy.allowSystemProperty";
    permission java.lang.RuntimePermission "accessClassInPackage.sun.net.www.protocol.c";
    permission java.security.SecurityPermission "getProperty.login.config.url.1";
    permission javax.security.auth.AuthPermission "refreshLoginConfiguration";
    // The following permission assumes the JAAS configuration is stored in
    // a file named login.config stored in the domain's home directory.  Adjust
    // as necessary.
    permission java.io.FilePermission "${domain.home}${/}login.config", "read";

Note that the last of these permissions is granting read permission to a file named login.conf, which has been placed in the home directory of the domain. Adjust this permission as needed to meet your particular requirements.

Troubleshooting Permission Problems

There is a simple, straight forward process to troubleshoot permission problems. This is fortunate, because the actual permission failure isn't always obvious from displayed or logged error output. For example, a permission failure might cause an exception that is caught by error handling which doesn't specifically address permission failures. The permission failure gets treated as a more general form of failure and the actions taken by the error handling can often hide the real source of the problem.

The first step of the process is to add "java.security.debug=access,failure" as a System property as described in the section Specifying JVM Runtime Permissions. This will greatly increase the server's log output and somewhat slow the server, but it will make permission problems much easier to find. The second step is to start, or restart, the managed server and perform any additional steps needed to create the problem. Finally, open the appropriate log file in an editor which is able to handle large files. If the editor you use is able to detect external changes to the file, you might want stop the managed server so it won't continue to make additions to the log file.

If the problem occurs during startup of the managed server, open the most recent startServer_*.log file found in the NodeManagerClientLogs\<domain name>_<server name> directory under your domain's home directory. If the problem occurs after startup, open the <server name>_error.log file found in the <domain name>_<server name> directory under <bea home>\weblogic81\common\nodemanager\NodeManagerLogs. If you are using WebLogic 8.1 SP1 on Windows, this location assumes the correction to the startNodeManager.cmd file has been made as described in the Installation Issues section.

Once the log file is open in the editor, search for the string, "access denied" (without the quotes). The line that this finds will show the permission that is needed, but missing from those that have been granted. Next, search for "domain that failed" (without the quotes), or manually scroll a little beyond the stack trace that follows the "access denied" line to find this line. The "domain that failed" line will show the codeBase that is requesting this permission. The last portion of the diagnostic output will be a little below the "domain that failed" line and look something like:

<no principals>
 java.security.Permissions@92d6d2 (
 (java.util.PropertyPermission java.specification.version read)
 ...
 (javax.security.auth.AuthPermission getLoginConfiguration)
)

This portion of the output lists all of the permissions currently granted to the codeBase shown in the "domain that failed" line. This output is useful if the problem is due to an existing permission that contains an error. Hopefully from this information, it will be possible to determine what permission needs to be added, or corrected, and for which grant blocks.

Note that not all permission failures represent unrecoverable errors. For example, a PropertyPermission failure won't cause a problem if a suitable default value is used when the permission failure occurs. If a web application tries to instantiate a Xalan XSLT transformer, it would not be unusual to see the following in the log output, which results from a call to System.getProperties().

access denied (java.util.PropertyPermission * read,write)

This is a permission failure from which Xalan recovers, and won't cause a problem in most situations.

If you have a webAF Web application project that contains a java.webapp.policy file, you will find that it contains the following optional permissions that avoid some recoverable permission failures that might otherwise occur in Web applications using the SAS Runtime Classes option.

  permission java.lang.RuntimePermission "modifyThread";
  permission java.lang.RuntimePermission "modifyThreadGroup";

If you are unsure whether a particular permission failure is part of the problem being investigated, you can temporarily add the permission. Once the problem is eliminated, remove the permission and see if the problem returns. If the problem doesn't return, then the permission is optional. If it is a permission that doesn't represent much of a security risk, such as the permission to read one or more System properties, you may decide to include it just to reduce the number of unnecessary permission failures.

Known WebLogic Issues

The behavior of WebLogic 8.1, WebLogic 8.1 SP1, and WebLogic 8.1 SP2 differ from the behavior provided by AppDev Studio's Servlet 2.3/JSP 1.2 Web Server with respect to when the ServletContextListener contextInitialized() method is called. During startup, AppDev Studio's Servlet 2.3/JSP 1.2 Web Server calls the contextInitialized() method prior to initializing filters and preloaded servlets. WebLogic 8.1, 8.1 SP1, and 8.1 SP2 do the opposite, calling the contextInitialized() method after initializing filters and preloaded servlets. Details in the Servlet 2.3 specifications are not sufficient to say definitively which behavior is correct. In the Servlet 2.4 specifications, this is clarified and servlet containers implementing this specification must call the contextInitialized() method prior to initializing filters and preloaded servlets.