Resources

SAS AppDev Studio 3.3 Developer's Site

WebLogic Deployment Information for SAS AppDev Studio

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

This document covers the BEA WebLogic Server 8.1 SP3. 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 is preferred for production deployment. However, if you chose another approach, such as using batch scripts, the information below can still apply.

This document covers the following topics:

Deployment Strategies

This section 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.

To use the Deployment Assistant in the Administration Console, follow these steps:

  1. Start the Deployment Assistant by:

    • Clicking Web Application Modules in the WebLogic Server Home page of the Administration Console.
    • Selecting Web Application Modules under Deployments in the tree on the left.
  2. 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 (with the Deploy button) of the Deployment Assistant.

Note: For simplification, the sections below assume that you have used the default deployment name and that it is the same as the context name.

When you create a WAR file using the SAS AppDev Studio 3.2 Eclipse Plug-ins, the filename can be arbitrarily chosen. Deployment will be simplified if you choose a name that matches what you want for the deployed context name. 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:

C:\bea\user_projects\domains\mydomain\myserver\upload

Note that a number of SAS components that are stored in HTTP session attributes are not serializable. Because the session attribute is not serializable, or it contains an object that is not serializable, it will not be able to migrate to the other servers in a cluster. As a result, the clustering features of WebLogic will not be available to the Web application. For the same reason, session persistence will not work for these attributes. Thus, these attributes will be lost if the Web application is redeployed or the managed server restarted.

In addition to deploying the Web application, there might be other files or resources that you need to deploy to the WebLogic server to support 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 the JAAS configuration files and Java policy file permissions. For SAS Web Application Projects created with the SAS AppDev Studio Eclipse Plug-ins, such files are found in the root directory of the project. These can include the launchParameters.txt, java.webapp.policy, and login.config files.

Serving the WAR File or a Source Directory

WebLogic 8.1 SP3 supports serving Web applications from WAR files and from source directories. You also have a choice of nostage or stage mode of deployment. If you choose to serve a WAR file using nostage mode, the Web application will be served directly from the WAR file.

To use the nostage mode of deployment, follow these steps:

  1. Open the Deployment Assistant in the WebLogic Administration Console.
  2. On the "Review your choices and deploy" page, under the Source Accessibility section, select the I will make the Web Application module accessible from the following location option. This selects the nostage mode of deployment. Note that the text field below this option should already contain the path for the WAR file.

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

Using stage mode is the alternative to using nostage mode. 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. In stage mode, the content of the Web application is copied to a staging directory, from which it is served. To use stage mode, follow these steps:

  1. Open the Deployment Assistant in the WebLogic Administration Console.
  2. On the "Review your choices and deploy" page, under the Source Accessibility section, select the Copy this Web Application module onto every target for me option. This selects the stage mode of deployment. If you are deploying a WAR file, its contents will be expanded when the server copies it to the staging directory.

Updating the WebLogic Managed Server Settings

Specifying the JVM Options and the Start-Up System Properties

To set the JVM options and the start-up system properties, follow these steps:

  1. Open the WebLogic Administration Console and navigate to the managed server that you want to configure.

  2. Select the Configure tab on the upper row.

  3. Select the Remote Start tab from the lower row.

  4. In the Arguments field, enter the JVM options and start-up system properties

  5. Click Apply. If the managed server is already running, you will have to restart it to have the new settings take effect.

You will need to collect and merge the JVM options and the start-up system properties for each Web application with any existing options and properties already in use. Also, you will have to resolve any conflicts, for example, determining the appropriate memory size options for the combination of Web applications that will be running. Some system property names might need to be altered if multiple Web applications are using the same name, but need to specify different values. Such changes will need to propagate to any resources that make use of those system properties.

In the SAS AppDev Studio Eclipse Plug-ins, the SAS Web Application Projects that you create using the SAS Web application templates will likely have a launchParameters.txt file in the root of the project. This file contains the JVM options and the start-up system properties that are required to run the Web application using the Tomcat server that is created as part of the SAS AppDev Studio setup. These arguments are the minimum that you need to include for deployment. The launchParameters.txt file might also contain comments that you should review for relevance prior to deploying the Web application.

If you are testing the Web application in the SAS AppDev Studio Eclipse Plug-ins environment, then there will be an Eclipse launch configuration that contains the JVM options and the start-up system properties used by the test server. This launch configuration could include additional arguments, or arguments that differ from those documented in the launchParameters.txt file. You should review the Java launch configuration for the test server to determine if any of its arguments are relevant for WebLogic deployment.

To display the JVM options and the start-up system properties in the server's launch configuration, follow these steps:

  1. Select Run [arrow] Run from the Eclipse menu bar to open the Run window.

  2. In the Configurations tree on the left, select the category for the server.

    Tomcat servers will be under the Apache Tomcat category. Other servers will likely be found under the Generic Server category.

  3. Select the Arguments tab. The JVM options and the start-up system properties are found in the VM Arguments field.

    If you are testing with a Tomcat server, certain arguments are relevant only to the Tomcat environment. These are the catalina.base, catalina.home, java.endorsed.dirs, and wtp.configured.security system properties. The java.security.manager and java.security.policy system properties, if present, would be set according to your WebLogic environment as described in later sections.

In the launchParameters.txt file, you will find one or more system properties that define host names and port numbers for various SAS Intelligence Platform servers accessed by the Web application. Examples include the sas.omr.host, sas.omr.port, and sas.workspace.host system properties, which are typically referenced in security permissions required by the Web application when deployed with a security manager enabled. The purpose of these system properties is to make the permissions configurable and to keep you from having to manually edit the permissions when they are copied to the managed server's policy file.

Specifying the JVM Run-Time Permissions

In WebLogic 8.1 SP3, you can specify run-time permissions in the weblogic.xml file, which can be included in the WEB-INF directory of your Web application. However, this approach is not discussed in this section, because it is not usable with the permissions required by Web applications that use SAS Foundation Services. Those permissions include some that depend on classes found in the WEB-INF/lib directory for the Web application. WebLogic tries to instantiate these permissions before the classes are available, which causes errors. If the permissions that your Web application requires do not have this kind of dependency, then you should investigate placing them in the weblogic.xml file.

The alternative to using the weblogic.xml file is to use the JVM supported java.security.policy system property to specify the path to a policy file. This system property is unique in that it uses equal signs to indicate whether the specified policy file should appended to or replace the default permissions. Use

Specifying a java.security.policy system property in the Arguments text field on the Run window, as described previously, is not the only way to specify the Java policy file for a WebLogic-managed server. The WebLogic Administration Console provides a field that you can use to specify the policy file. To specify the policy file, follow these steps:

  1. Open the WebLogic Administration Console and navigate to the managed server that you want to configure.

  2. Select the Configure tab in the upper row.

  3. Select the Remote Start tab in the lower row.

  4. In the Security Policy File text field, enter the path for your policy file.

  5. Click Apply.

    Specifying the policy file in this way causes the java.security.policy system property to be added using the double equal sign (==) 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, you should not modify the WebLogic weblogic.policy file found in the <BEA home>\weblogic81\server\lib directory to add permissions intended for node managed servers. Instead, copy the weblogic.policy file to your domain's home directory, or other suitable location, and then use this copy 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.

In WebLogic 8.1 SP3, assigning permissions that apply only to a single Web application requires two grant blocks for that 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 the 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 the maintenance of these permissions.

For a managed server, the codeBase value for the grant block that covers JAR files will be determined with respect to the BEA installation directory, the managed server's name, the name of the Web application's WAR file or source directory, and the Web application's deployment name.

Note: As stated in the Deployment Strategies section, this document assumes that you are using the default value for the deployment name. This means the deployment name 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 new system properties (bea.home, server.name, and myapp.name) to specify the BEA home directory, the server name, and the Web application name. For multiple Web applications, you need to substitute a unique system property name for the myapp.name parameter name for each Web application. The system property name that you choose must also be substituted where ever it appears in any other grant blocks and permissions.

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 either 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, you should append a slash and a minus sign (/-) so that all of the subdirectories are included.

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

// 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 a new system property (domain.home), to specify the domain's home directory. This is in addition to the bea.home, server.name, and myapp.name properties that were previously mentioned.

For staged mode deployment, the codeBase value for the grant block that covers classes in WEB-INF/classes is also determined based on the same three parameters used in the first grant block. You can use one of the following two grant blocks for either WAR file or source directory deployment, provided that the server's 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 you deploy multiple Web applications, make sure that the system property name in this grant block matches the system property name that is used in the first grant block for those whose name was changed from myapp.name.

For SAS Web Application Projects, there will typically be a java.webapp.policy file in the root directory of the project. This policy file is designed for use with Tomcat v4.1. However, it can also be used as the source of permissions for WebLogic 8.1 SP3.

The permissions for the Web application are found in the grant blocks that follow the

"// ========== project name Web Application Permissions =========="

comment line in the file. These three grant blocks from the java.webapp.policy file should be combined into a single set of permissions, which is placed in both grant blocks for the Web application in the policy file for the managed server. You need to add any system properties that the permission depends on to the managed server's start-up parameters as described in the Specifying JVM Options and Start-Up System Properties section.

If your Web application uses 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";

These run-time permissions should be in included in both of the grant blocks that you add for a Web application. Although it would be easier, these permissions cannot be specified in the weblogic.xml file for the reason described in the first paragraph of this section.

Enabling a Security Manager

To enable a security manager, include a java.security.manager system property in 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 a new java.security.manager system property, follow these steps:

  1. Open the WebLogic Administration Console and navigate to the managed server.

  2. Select the Remote Start tab.

  3. In the Arguments field, add the java.security.manager system property.

  4. Click Apply to add the new security manager.

When you enable a security manager, you need to add some other 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 Run-Time Permissions section will be used.

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

// Needed by WebLogic 8.1 SP3, if a Web application compiles JSP files at run time
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";
};

Also, you can add the permissions listed below to both grant blocks for each Web application so that typical operations, such as session creation and JSP compilation, do not throw security exceptions:

// Needed by WebLogic 8.1 SP3 for typical operation and for compiling JSP files at run time
  permission java.lang.RuntimePermission "accessClassInPackage.sun.io";
  permission java.lang.RuntimePermission "weblogic.kernelPermission";

  permission java.io.FilePermission "${domain.home}${/}applications${/}-", "read";
  // Optionally, you can be more restrictive by commenting out the above line and 
  // uncommenting the three following lines.
//permission java.io.FilePermission "${domain.home}${/}applications${/}${myapp.name}${/}-", "read";
//permission java.io.FilePermission "${domain.home}${/}applications${/}${myapp.name}.war", "read";
//permission java.io.FilePermission "${domain.home}${/}applications${/}APP-INF${/}-", "read";

  permission java.io.FilePermission ".${/}${server.name}${/}${server.name}.log", "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 system property name that is being used by their 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 SP3, 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 that 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 grants read permission to a file named login.config, 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, straightforward process to troubleshoot permission problems. This is fortunate, because the actual permission failure is not always obvious from the displayed or logged error output. For example, the error handling that catches a security exception might not be written to specifically to address permission failures. Thus, the permission failure might get treated as a more general form of failure and the actions taken by the error handling might hide the real source of the problem.

To troubleshoot permission problems, follow these steps:

  1. Add java.security.debug=access,failure as a system property. This will greatly increase the server's log output and somewhat slow the server, but it will make permission problems much easier to find.

    For more information, see Specifying the JVM Run-Time Permissions.

  2. Start (or restart) the managed server and perform any additional steps that are needed to re-create the problem.

  3. Open the appropriate log file in an editor that 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 that it will not continue to make additions to the log file.

    If the problem occurs:

    • During startup of the managed server, then open the most recent startServer_*.log file, which is found in the NodeManagerClientLogs\<domain name>_<server name> directory under your domain's home directory.

    • After startup, then open the <server name>_error.log file, which is found in the <domain name>_<server name> directory under the <bea home>\weblogic81\common\nodemanager\NodeManagerLogs directory.

  4. Once the log file is open in the editor, search for the access denied text string. The line that this string finds will show the permission that is needed, but is missing from those that have been granted.

  5. Search for the domain that failed text string, or manually scroll a little beyond the stack trace that follows the line with the access denied text string to find this line.

    The line with the domain that failed text string will show the codeBase that is lacking this permission. The last portion of the diagnostic output will be a little below the line with the domain that failed text string and look something like this:

    <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 line with the domain that failed text string. 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 will not 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(), as follows:

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

This is a permission failure from which Xalan can recover, and it will not cause a problem in most situations.

If you have a SAS Web Application Project 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 SAS Web applications.

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

If you are not sure 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 does not return, then the permission is optional. If it is a permission that does not represent much of a security risk, such as the permission to read one or more system properties, you might decide to include it just to reduce the number of unnecessary permission failures.

Known WebLogic Issues

The FoundationServicesContextListener provided by Web application templates in SAS AppDev Studio Eclipse Plug-ins contains a note in its comments that refers to the ambiguity in the Servlet 2.3 specification about whether ServletContextListeners are initialized before or after preloaded servlets. This note was prompted by the behavior found WebLogic 8.1 SP2, and earlier, which initialized ServletContextListeners after preloaded servlets.

For Change Request CR134813, BEA has changed the behavior of WebLogic 8.1 SP3 to match the Servlet 2.4 specifications. In the Servlet 2.4 specifications, this behavior has been clarified and servlet containers implementing this specification must initialize ServletContextListeners prior to initializing filters and preloaded servlets. As a result, for WebLogic 8.1 SP3, the need to call the FoundationServicesContextListener's deployServices() method from servlet init() methods as described in the comments of the FoundationServicesContextListener.java file is not necessary.