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:
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:
Start the Deployment Assistant by:
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.
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:
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:
To set the JVM options and the start-up system properties, follow these steps:
Open the WebLogic Administration Console and navigate to the managed server that you want to configure.
Select the Configure tab on the upper row.
Select the Remote Start tab from the lower row.
In the Arguments field, enter the JVM options and start-up system properties
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:
Select Run Run from the Eclipse menu bar to open the Run window.
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.
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.
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
a single equal sign (=
) to indicate that the permissions
should be appended to the default permissions.
double equal signs (==
) to indicate that the permissions
should replace the default permissions.
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:
Open the WebLogic Administration Console and navigate to the managed server that you want to configure.
Select the Configure tab in the upper row.
Select the Remote Start tab in the lower row.
In the Security Policy File text field, enter the path for your policy file.
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.
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:
Open the WebLogic Administration Console and navigate to the managed server.
Select the Remote Start tab.
In the Arguments field, add the java.security.manager
system property.
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.
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:
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.
Start (or restart) the managed server and perform any additional steps that are needed to re-create the problem.
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.
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.
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.
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.