Editing a JSP deployment configuration

The Deployment
Configuration Properties dialog box for a JSP target includes properties
for:

• “General deployment options”
• “JSP deployment options”

When you deploy the JSP target, PowerBuilder builds a Web
Archive (WAR) file in the deployment configuration folder created
by the JSP Web Target wizard. The WAR file contains the JSP files
you added to the target, any classes or JAR files you added to the Source folder,
and a web.xml file that conforms to the Document
Type Definition (DTD) for Web applications. The Web application
is automatically deployed to the server you selected in the target wizard.

The web.xml file is the deployment descriptor
for the Web application. The deployment configuration properties
you define in the JSP Options section of the JSP Deployment Configuration
Properties dialog box are written to the web.xml file.

In general, you should not edit the web.xml file
manually. The changes you make in the Deployment Configuration Properties
dialog box are propagated to copies of the web.xml file
in the WAR file and appropriate subdirectories of your JSP target.

You open the Deployment Configuration Properties dialog box
for a JSP target in the same way as for a Web site target: select
Properties from the target’s pop-up menu and double-click
the deployment configuration you want to view or edit on the Deploy
page of the Target Properties dialog box.

General deployment options

The general
deployment options of a JSP target allow you to:

• Enter
  a description for the deployment configuration
• Enter server information
• Include the JSP object model in the deployment archive
• Select a build strategy and how you want to handle
  deployment errors

You cannot change the deployment configuration name from the
Deployment Configuration Properties dialog box. If you want to create
a different deployment configuration name, close this dialog box
and start the Name New Deployment Configuration wizard from the
Deploy page of the Properties dialog box for the target.

The general deployment options for a JSP target consist of
four main selection pages that you access from the tree view in
the Deployment Configuration Properties dialog box:

Table 11-4: General deployment
configuration options for a JSPtarget

Deployment selection page	Description
General	Type a description for the deployment configuration.
Server Information	Lists the server types to which you can deploy. The current selection is highlighted. Additional selections are available depending on which server you select: EAServer Select a deployment profile and an HTTP port. Tomcat Select the deployment folder and the HTTP server and port. You can also select a login name and password, and choose to stop and restart the server automatically after the target is deployed. Custom Command Line Type deployment commands required for deploying the target WAR file to a JSP server other than EAServer or Tomcat. You can use macros to build the command lines and select options allowing you to abort deployment on detection of an error, show deployment messages in the output window, or create the target WAR file from the command line (by blocking PowerBuilder from generating the WAR file).
Object Model	Select whether you want to deploy the JSP object model with your JSP target. You can select the default JSP object model only.
Deploy What?	Select Deploy All Or Nothing to make sure that nothing gets deployed when one of the files selected for deployment fails the build or predeployment processing. Select Deploy Only Successful Files to prevent failure of a single file from affecting deployment of other files in the target.The Rebuild field lets you select whether to use an incremental or full rebuild of files you select for deployment with the current configuration. Local Copy Folder When you build the JSP target, PowerBuilder generates a WAR file containing JSP files and supporting objects in the folder you specify as the Local Copy Folder. You can clear the Make Local Copy Of Deployed Files check box only if you selected the Deploy Only Successful Files option.

JSP deployment options

The JSP options that you specify in the Deployment Configuration
Properties dialog box are added to the web.xml deployment
descriptor for the WAR file that contains the Web application. These
properties are defined under the following dialog box headings:

JSP options	Mime Mapping	Security
Context Params	Welcome Files	Environment
Filters	Error Mapping	EJBs
Listeners	Tag Libraries
Servlets	Resource References

JSP options

Web Application Name

The Web Application Name is the display name used on the server
to identify a deployed WAR file.

Description

Use
the description box to provide any information that might be required
by the consumer of the application.

Session Timeout

Session
Timeout is a specified time in minutes after which the server will terminate
servlet sessions. This value applies to all the servlets within
an application. A value of 0 indicates that servlet sessions never
expire.

Distributable

Web
applications can run on only one Java VM at any one time. To override this
rule, you must mark the Web application as distributable in the
deployment descriptor. However, the application must conform to
additional requirements. A distributable Web application cannot
use setAttribute and putValue methods to
place objects into a javax.servlet.http.HttpSession object
unless the object is one of the following types:

• java.io.Serializable
• javax.ejb.EJBObject
• javax.ejb.EJBHome
• javax.transaction.UserTransaction
• javax.naming.Context object for
  the java:comp/env context

For more information, see the Java Servlet specification,
available
.

Context Params

The Context Params page is where you specify the value of
parameters that convey initialization information for the Web application,
such as a Web master’s address or the name of a system
that holds critical data. They can be retrieved using the getInitParameter and getInitParameterNames methods
of the ServletContext interface.

In a JSP page, the parameter can be retrieved in a scriptlet
using the application implicit object, for example:

PowerBuilder

&lt;%<br /> String iURL = application.getInitParameter("iURL");<br /> %&gt;

1	&lt;%<br />    String iURL = application.getInitParameter("iURL");<br /> %&gt;

Filters

Filter Content

You
can write a filter to modify requests and responses and then declare
it on the Filters page. Filters implement the javax.servlet.Filter interface.

Table 11-5: Filter content
properties for a JSP target

Setting	Value
Filter Name	Specify the name of the filter, for example Image Filter
Filter Class	Specify the fully qualified class name of the filter, for example com.acme.ImageServlet
Init Parameters	Specify initialization parameter names and values for each filter that you select

For more information about filters, see the Java Servlet specification
or the EAServer Programmer’s Guide
.

Filter Mapping

The
container uses the filter mappings you specify on the Filter Mapping
page to determine how to apply the filters that have been defined
to requests. You can apply a filter to a single servlet by specifying
its name, or to a group of servlets and other Web content by specifying
a URL pattern. For example, * specifies that
a filter applies to all servlets in the Web application. The filters are
applied in the order in which they appear in the list of filter-mapping elements
in the deployment descriptor.

Listeners

You
can provide listener classes implementing one or more of the listener classes
in the Servlet API. Listeners can support event notifications or
manage resources or state. You package the listener classes in the
WAR file and list them in the deployment descriptor in the order
in which they are to be invoked.

Servlets

Servlet Details

Use the servlet pages to describe a servlet class or JSP page
used in the Web application. Click New to give the servlet or page
a short name that can be used to reference it. Then select Servlet
Class or JSP Filename from the drop-down list box. For servlets,
you must specify the fully qualified class name in the text box
next to the drop-down list box.

If you want to see target JSPs listed in the management tool
for your server, you must enter a short name for each JSP, select
JSP Filename from the drop-down list box, and enter the JSP file
name in the text box next to the drop-down list box. However, this
information is not required for access to the JSPs from a client
browser.

You can specify the following properties for each servlet
or JSP from the Deployment Configuration Properties dialog box: Load on Startup, Init Param, Role Refs, and Servlet Mapping URL Pattern.

Load on Startup

Load
on Startup indicates whether you want a servlet loaded and initialized when
the application is deployed. Otherwise, the servlet class is loaded
when the first client requests it. Servlet classes that perform
lengthy processing in the init method can be
loaded at start-up so that the first client to invoke the servlet does
not experience increased response time.

A value of 0 or a positive integer requires the container
to load the servlet when the application is deployed. Servlets with
a low Load on Startup value are loaded before those with a higher
value. If you do not specify a value, or if you specify a negative
integer, the container can load the servlet at any time.

Init Param

Use
the Init Param table to assign values of parameters specifying setup information
for the servlet or JSP page. In a JSP page, the parameter can be retrieved
in a scriptlet using the config implicit object,
for example:

PowerBuilder

&lt;%<br /> String initVal = config.getInitParameter("initVal");<br /> %&gt;

1	&lt;%<br />    String initVal = config.getInitParameter("initVal");<br /> %&gt;

Role Refs

Role references provide a mechanism an application can use
to map a role name used in the application’s code to a
security role defined in its deployed environment.

Table 11-6: Role reference
properties for a JSP target

Setting	Value
Name	Name of the security role used as a parameter to the IsCallerInRole method
Description	(Optional) A comment to explain how the property is used
Link	The security role (see “Roles”) to which this reference should be linked

Servlet Mapping URL Pattern

A servlet mapping defines the association between a URL pattern
and a servlet. This mapping is used to map requests to servlets.
The default is /ServletTargetName,
for example /MyServlet.

If the container handling the request is a JSP container,
a URL containing a .jsp extension is implicitly
mapped.

Mime Mapping

Specify
mime mappings to ensure that the Web container knows how to associate
a file extension with a mime type. For example, if you specify .txt as the
extension, you must specify a predefined mime type such as text/plain.

Welcome Files

The
welcome file list contains an ordered list of welcome file elements
to be used when the container receives a valid partial request.
A valid partial request is a request for a URI that corresponds
to a directory entry in the WAR not mapped to a Web component.

For example, if the container receives a request for //myhost:8080/myapp/mydir,
and mydir is not mapped
to a servlet or JSP file, then if the welcome file list includes
the mapping mydir/index.html, index.html is
displayed.

Error Mapping

You
can customize what the client sees when an error or an exception
is generated by specifying the locations of error pages for different
kinds of errors. Error pages you specify here are used for servlets
and for any JSP pages that do not specify an error page for the
error type.

In the left column, you can specify an HTTP error code, for
example 404, or a fully qualified class name of a Java exception
type. In the right column, specify where to find the resource in
the Web application relative to the root of the Web application.
The value of the location must have a leading forward slash ( / ). For
example, /404.html.

PowerBuilder adds the following elements to the target Web.xml file
depending on the value in the Error column:

Table 11-7: Element added
to target Web.xml file

Error column value	Element added to Web.xml file
Y	<error-code>
N	<exception-type>

If you specify an exception class in the left column rather
than an HTTP error code, you must
change the
Error column value to N. Otherwise you may have problems deploying
or running the target, depending on the JSP container to which you
deploy, or try to deploy, your target.

Tag Libraries

If
the Web application uses one or more tag libraries, you can make
sure that the Web container can locate them by specifying a mapping
for each tag library in the deployment descriptor. If you selected
tag libraries in the JSP Web Target wizard, they display here.

You use a taglib directive to refer to a tag library in a
JSP page. For example:

PowerBuilder

&lt;%@ taglib uri="/WEB-INF/tlds/mycalc.tld" prefix="mc" %&gt;

1	<%@ taglib uri="/WEB-INF/tlds/mycalc.tld" prefix="mc" %>

The uri attribute specifies the uniform resource locator (URI)
for the TLD file relative to the root of the Web application. You
can map this path to a short name in the deployment descriptor.
Specify the name you want to use in the Tag Library URI column,
and the location relative to the root of the Web application in
the Descriptor File Location column.The value of the location must
have a leading forward slash ( / ). For example, /WEB-INF/tlds/Testlibrary_1_3.tld.

If you specify /mycalc as
the short name for the
/WEB-INF/tlds/mycalc.tld,
the taglib directive can be written like this:

PowerBuilder

&lt;%@ taglib uri="/mycalc" prefix="mc" %&gt;

1	<%@ taglib uri="/mycalc" prefix="mc" %>

Resource References

References

To be
platform independent, an application should refer to resources within
the operating environment in which it is deployed, rather than having
a specific location coded within the application. The J2EE specification
defines a mechanism for an application to obtain resource references
in its deployed environment. Resource references are used to obtain
database connections, JavaMail sessions, URL factories, and JMS
connection factories.

Table 11-8: Resource
reference properties for a JSP target

Setting	Value
Name	Specify the JNDI name used to refer to a resource. Use the prefix mail/ for JavaMail references, jdbc/ for data source references, url/ for java.net.URL references, and jms/ for javax.jms references. For example, if your code refers to java:comp/env/jdbc/MyDatabase, enter jdbc/MyDatabase.
Type	Use one of these resources: javax.sql.DataSource for JDBC connections java.net.URL for URL factories javax.mail.Session for mail sessions javax.jms.QueueConnectionFactory for a JMS queue javax.jms.TopicConnectionFactory for a JMS topic
Authentication	Enter: Container if the container signs on to the resource manager on behalf of the servlet component. The methodology used to sign on is server specific. Application if the application signs on programmatically to the resource manager. Servlet if the servlet (not the container) signs on programmatically to the resource manager.
Sharing Scope	By default, connections to a resource manager can be shared by other components that use the resource in the same transaction context, optimizing the use of connections. Select Unshareable if the application cannot share connections to the resource.
Description	(Optional) A comment to explain how the property is used.

Env References

Resource
environment references allow the JSP page to use logical names to refer
to administered objects associated with resources. These references
must be bound to administered objects in the deployment environment.

Table 11-9: Environment
reference properties for a JSP target

Setting	Value
Name	Specify a name for a reference to an administered object associated with resources, such as a JMS message queue. The name is relative to the java:comp/env context, for example jms/MyQueue.
Type	Specify the type of the resource, for example javax.jms.Queue.
Description	(Optional) A comment to explain how the property is used.

Security

Security Constraints

Security
constraints let you control access to a Web resource collection.
A Web resource collection identifies the resources, defined by URL
patterns, and the HTTP methods on those resources, to which the
security constraints apply. The security constraints define the
roles authorized to use the Web resource collection (authorization
constraint) and the level of transport security required of the
client server (user data constraint).

You define the Web resource collection and its constraints
on the Security Constraints page.

If you do not assign a user role, no user has access to the
resources in the specified collection. If you do not specify HTTP
methods, the constraints apply to all methods.

Table 11-10: Security
constraint properties for a JSP target

Setting	Value
Name	Specify a name for the Web resource collection.
URL Pattern	Select one or more URL patterns to specify the resources in this Web application to which the constraints apply.
HTTP Methods	(Optional) Specify the HTTP methods to which the constraints apply. If you do not specify any methods, the constraints apply to all methods.
Authorized Roles	Select the roles authorized to access the collection of Web resources defined in the URL Pattern and HTTP Methods boxes. You can define roles on the Roles page of the Deployment Configuration Properties dialog box.
Transport Guarantee	Establish a level of transport security appropriate for the Web resources you are protecting. If you use basic or form-based authentication, passwords and other sensitive information are not protected for confidentiality. If you have sensitive information that you want to protect, establish a security constraint that uses a greater level of protection: NONE – uses insecure HTTP. SSL-protected sessions require more overhead than insecure HTTP sessions. Use none for transport guarantee if you do not need the added confidentiality of SSL. INTEGRAL – uses an SSL-protected session that checks for data integrity. CONFIDENTIAL – uses an SSL-protected session to ensure that all message content, including the client authenticators, is protected for confidentiality as well as data integrity. A confidential transport guarantee has more overhead than none.

Login Configuration

Protected
resources on a server can be partitioned into separate protection spaces.
Each protection space can be configured with a specific security scheme,
such as an authentication protocol or authorization database. When
a Web server asks a client to authenticate a user, it passes a realm
to the client. A realm is a string that defines a protection space.

Use of the term realm In J2EE applications, the term realm is also used to refer
to a security policy domain. In this deployment descriptor, it refers
to the string passed as part of HTTP basic authentication.

The client passes the user name and password to the Web server,
and the Web server authenticates the user in the specified realm.The
login-config element is used to configure the authentication method,
the realm name that should be used for this application, and the
attributes that are needed by the form login mechanism.

Table 11-11: Login authentication
properties for a JSP target

Setting	Value
Authentication Method	Select the authentication method to be used to configure the authentication mechanism for the Web application: BASIC – the server asks the client for a user name and password. You must also provide a realm name. DIGEST – advanced form of BASIC authentication using an MD5 message-digest hash of the credentials and a unique value supplied by the server: the password is not sent in clear, unencrypted text as with BASIC authentication. FORM – the Web application developer creates an HTML login page, where the client enters a user name and password. The entire HTML page is sent to the server. You also create an error page that is returned to the client in the event of a server error. CLIENT-CERT – the client connects to the server using SSL tunneled within HTTP. The client must provide a certificate that the server accepts and authenticates.
Realm Name	Specify the realm name to be used in HTTP basic authentication.
Form Login Page	Specify the location in the Web application where the page to be used for login can be found. The path begins with a leading / and is interpreted relative to the root of the Web application.
Form Error Page	Specify the location in the Web application where the error page that is displayed when login fails can be found. The path begins with a leading / and is interpreted relative to the root of the Web application.

Roles

A
security role is a grouping of permissions that a given type of
user of an application must have to successfully use an application
and its components. The Roles page allows you to define security
roles, for example admin or user, that
you can associate with specific resources on the Security Constraints
page.

Environment

Environment
properties allow you to specify global read-only data for use by all
the JSP pages in the Web application.

Servlets and JSP pages must use JNDI to retrieve environment
properties, using the prefix java:comp/env in
JNDI lookups. Unlike context initialization properties, environment
properties can have datatypes other than java.lang.String.

The deployment descriptor catalogs the environment properties
used by your servlets and JSP pages, as well as each property’s
Java datatype and default value. You can tailor the values to match
a server’s configuration. For example, you may have environment
properties to specify the name of a logging file or to tune cache
usage.

Table 11-12: Environment
properties for a JSP target

Setting	Value
Name	Specifies the JNDI name, relative to the java:comp/env prefix, used in servlet and JSP code to refer to this resource.
Type	Select the Java datatype of the property from the drop-down list box. The specified type must have a constructor that takes a single java.lang.String argument.
Value	The initial or post-deployment value of the property, specified as text that is valid for the type constructor that takes a single java.lang.String argument.
Description	(Optional) A comment to explain how the property is used.

EJBs

EJBs that support the EJB 2.0 specification can have both
remote and local interfaces.

EJB References

When
servlets and JSP pages reference remote EJBs, the EJB reference
in the deployment descriptor is used to instantiate proxies for
EJB home interfaces. EJB references must be catalogued in the deployment
descriptor so that the Web application does not depend on a specific
naming configuration. When deploying the Web application, a site
administrator can specify site-specific EJB home names.

Table 11-13: EJB reference
properties for a JSP target

Setting	Value
Name (New button)	Click New to create a new remote reference to an enterprise bean. Specifies the JNDI name used to refer to this EJB.
Type	Choose Session for session beans or Entity for entity beans.
Home Interface	The Java class name of the EJB home interface, specified in dot notation. For example, com.sybase.myBeanHome.
Remote Interface	The Java class name of the EJB remote interface, specified in dot notation. For example, com.sybase.myBeanRemote.
Description	(Optional) A comment to describe the EJB reference.
Link	The JNDI name of an instance of the specified EJB that is installed in the server where the Web application is to be deployed.

Local References

Servlets
and JSP pages can reference EJBs running in the same Java VM using local
interfaces. The settings for EJB local references are analogous
to the settings for EJB references, which are used when the EJB
is not running in the same Java VM.

Table 11-14: Local EJB
reference properties for a JSP target

Setting	Value
Name (New button)	Click New to create a new local reference to an enterprise bean. Specifies the JNDI name used to refer to this EJB.
Type	Choose Session for session beans or Entity for entity beans.
Local Home	The Java class name of the EJB local home interface, specified in dot notation. For example, com.sybase.shopping.LocalCartHome.
Local Interface	The Java class name of the EJB local interface, specified in dot notation. For example, com.sybase.shopping.LocalCart.
Description	(Optional) A comment to describe the local EJB reference.
Link	The JNDI name of an instance of the specified EJB that is installed in the server where the Web application is to be deployed.

---