Sun GlassFish Enterprise Server v3 Prelude Application Deployment Guide

S

sas-context

Describes the sas-context fields.

Superelements

ior-security-config (sun-ejb-jar.xml)

Subelements

The following table describes subelements for the sas-context element.

Table A–75 sas-context Subelements


Element	Required	Description
caller-propagation	only one	Specifies whether the target accepts propagated caller identities. The values are NONE, SUPPORTED, or REQUIRED.

schema-generator-properties

Specifies field-specific column attributes in property subelements.

Note –

This element is not implemented for GlassFish v3 Prelude.

Superelements

cmp-resource (sun-ejb-jar.xml)

Subelements

The following table describes subelements for the schema-generator-properties element.

Table A–76 schema-generator-properties Subelements


Element	Required	Description
property (with subelements)	zero or more	Specifies a property name and value.

Properties

The following table describes properties for the schema-generator-properties element.

Table A–77 schema-generator-properties Properties


Property	Default	Description
`use-unique-table-names`	`false`	Specifies that generated table names are unique within each application server domain.
`bean-name.field-name.attribute`	none	Defines a column attribute. For attribute descriptions, see Table A–78.

The following table lists the column attributes for properties defined in the schema-generator-properties element.

Table A–78 schema-generator-properties Column Attributes


Attribute	Description
`jdbc-type`	Specifies the JDBC type of the column created for the CMP field. The actual SQL type generated is based on this JDBC type but is database vendor specific.
`jdbc-maximum-length`	Specifies the maximum number of characters stored in the column corresponding to the CMP field. Applies only when the actual SQL that is generated for the column requires a length. For example, a `jdbc-maximum-length` of `32` on a CMP `String` field such as `firstName` normally results in a column definition such as VARCHAR(32). But if the `jdbc-type` is `CLOB` and you are deploying on Oracle, the resulting column definition is CLOB. No length is given, because in an Oracle database, a CLOB has no length.
`jdbc-precision`	Specifies the maximum number of digits stored in a column which represents a numeric type.
`jdbc-scale`	Specifies the number of digits stored to the right of the decimal point in a column that represents a floating point number.
`jdbc-nullable`	Specifies whether the column generated for the CMP field allows null values.

Example

<schema-generator-properties>
   <property>
	     <name>Employee.firstName.jdbc-type</name>
	     <value>char</value>
   </property>
   <property>
	     <name>Employee.firstName.jdbc-maximum-length</name>
	     <value>25</value>
   </property>
   <property>
	     <name>use-unique-table-names</name>
	     <value>true</value>
   </property>
</schema-generator-properties>

security-role-mapping

Maps roles to users or groups in the currently active realm. See Realm Configuration in Sun GlassFish Enterprise Server v3 Prelude Developer’s Guide.

The role mapping element maps a role, as specified in the EJB JAR role-name entries, to a environment-specific user or group. If it maps to a user, it must be a concrete user which exists in the current realm, who can log into the server using the current authentication method. If it maps to a group, the realm must support groups and the group must be a concrete group which exists in the current realm. To be useful, there must be at least one user in that realm who belongs to that group.

Superelements

sun-web-app (sun-web.xml), sun-ejb-jar (sun-ejb-jar.xml)

Subelements

The following table describes subelements for the security-role-mapping element.

Table A–79 security-role-mapping Subelements


Element	Required	Description
role-name	only one	Contains the `role-name` in the `security-role` element of the corresponding Java EE deployment descriptor file.
principal-name	one or more if no `group-name`, otherwise zero or more	Contains a principal (user) name in the current realm. In an enterprise bean, the principal must have the run-as role specified.
group-name	one or more if no `principal-name`, otherwise zero or more	Contains a group name in the current realm.

service-endpoint-interface

Specifies the web service reference name relative to java:comp/env.

Superelements

port-info (sun-web.xml, sun-ejb-jar.xml)

Subelements

none - contains data

service-impl-class

Specifies the name of the generated service implementation class.

Superelements

service-ref (sun-web.xml, sun-ejb-jar.xml)

Subelements

none - contains data

service-qname

Specifies the WSDL service element that is being referred to.

Superelements

service-ref (sun-web.xml, sun-ejb-jar.xml); webservice-endpoint (sun-web.xml, sun-ejb-jar.xml)

Subelements

The following table describes subelements for the service-qname element.

Table A–80 service-qname subelements


Element	Required	Description
namespaceURI	only one	Specifies the namespace URI.
localpart	only one	Specifies the local part of a QNAME.

service-ref

Specifies runtime settings for a web service reference. Runtime information is only needed in the following cases:

To define the port used to resolve a container-managed port
To define the default Stub/Call property settings for Stub objects
To define the URL of a final WSDL document to be used instead of the one associated with the service-ref in the standard Java EE deployment descriptor

Superelements

sun-web-app (sun-web.xml), ejb (sun-ejb-jar.xml)

Subelements

The following table describes subelements for the service-ref element.

Table A–81 service-ref subelements


Element	Required	Description
service-ref-name	only one	Specifies the web service reference name relative to `java:comp/env`.
port-info	zero or more	Specifies information for a port within a web service reference.
call-property	zero or more	Specifies JAX-RPC property values that can be set on a `javax.xml.rpc.Call` object before it is returned to the web service client.
wsdl-override	zero or one	Specifies a valid URL pointing to a final WSDL document.
service-impl-class	zero or one	Specifies the name of the generated service implementation class.
service-qname	zero or one	Specifies the WSDL service element that is being referenced.

service-ref-name

Specifies the web service reference name relative to java:comp/env.

Superelements

service-ref (sun-web.xml, sun-ejb-jar.xml)

Subelements

none - contains data

servlet

Specifies a principal name for a servlet. Used for the run-as role defined in web-xml.

Superelements

sun-web-app (sun-web.xml)

Subelements

The following table describes subelements for the servlet element.

Table A–82 servlet Subelements


Element	Required	Description
servlet-name	only one	Contains the name of a servlet, which is matched to a `servlet-name` in `web.xml`.
principal-name	zero or one	Contains a principal (user) name in the current realm.
webservice-endpoint	zero or more	Specifies information about a web service endpoint.

servlet-impl-class

Specifies the automatically generated name of the servlet implementation class.

Superelements

webservice-endpoint (sun-web.xml, sun-ejb-jar.xml)

Subelements

none - contains data

servlet-name

Specifies the name of a servlet, which is matched to a servlet-name in web.xml. This name must be present in web.xml.

Superelements

cache-mapping, servlet (sun-web.xml)

Subelements

none - contains data

session-config

Specifies session configuration information. Overrides the web container settings for an individual web module.

Superelements

sun-web-app (sun-web.xml)

Subelements

The following table describes subelements for the session-config element.

Table A–83 session-config Subelements


Element	Required	Description
session-manager	zero or one	Specifies session manager configuration information.
session-properties	zero or one	Specifies session properties.
cookie-properties	zero or one	Specifies session cookie properties.

session-manager

Specifies session manager information.

Superelements

session-config (sun-web.xml)

Subelements

The following table describes subelements for the session-manager element.

Table A–84 session-manager Subelements


Element	Required	Description
manager-properties	zero or one	Specifies session manager properties.
store-properties	zero or one	Specifies session persistence (storage) properties.

Attributes

The following table describes attributes for the session-manager element.

Table A–85 session-manager Attributes


Attribute	Default	Description
`persistence-type`	`memory`	(optional) Specifies the session persistence mechanism. Allowed values are `memory`, `file`, and `replicated`. Note – The `replicated` persistence type is not supported in GlassFish v3 Prelude.

session-properties

Specifies session properties.

Superelements

session-config (sun-web.xml)

Subelements

The following table describes subelements for the session-properties element.

Table A–86 session-properties Subelements


Element	Required	Description
property (with attributes)	zero or more	Specifies a property, which has a name and a value.

Properties

The following table describes properties for the session-properties element.

Table A–87 session-properties Properties


Property	Default	Description
`timeoutSeconds`	`1800`	Specifies the default maximum inactive interval (in seconds) for all sessions created in this web module. If set to `0` or less, sessions in this web module never expire. If a `session-timeout` element is specified in the `web.xml` file, the `session-timeout` value overrides any `timeoutSeconds` value. If neither `session-timeout` nor `timeoutSeconds` is specified, the `timeoutSeconds` default is used. Note that the `session-timeout` element in `web.xml` is specified in minutes, not seconds.
`enableCookies`	`true`	Uses cookies for session tracking if set to `true`.
`enableURLRewriting`	`true`	Enables URL rewriting. This provides session tracking via URL rewriting when the browser does not accept cookies. You must also use an `encodeURL` or `encodeRedirectURL` call in the servlet or JSP.

steady-pool-size

Specifies the initial and minimum number of bean instances that are maintained in the pool. Default is 32. Applies to stateless session beans and message-driven beans.

Note –

This element is not implemented for GlassFish v3 Prelude.

Superelements

bean-pool (sun-ejb-jar.xml)

Subelements

none - contains data

store-properties

Specifies session persistence (storage) properties.

Superelements

session-manager (sun-web.xml)

Subelements

The following table describes subelements for the store-properties element.

Table A–88 store-properties Subelements


Element	Required	Description
property (with attributes)	zero or more	Specifies a property, which has a name and a value.

Properties

The following table describes properties for the store-properties element.

Table A–89 store-properties Properties


Property	Default	Description
`directory`	`domain-dir/generated/jsp/app-name/module-name_war`	Specifies the absolute or relative pathname of the directory into which individual session files are written. A relative path is relative to the temporary work directory for this web module. Applicable only if the `persistence-type` attribute of the parent session-manager element is `file`.
`persistenceScope`	`session`	Specifies how much of the session state is stored. Allowed values are as follows: `session` - The entire session state is stored every time. This mode provides the best guarantee that your session data is correctly stored for any distributable web module. `modified-session` - The entire session state is stored if it has been modified. A session is considered to have been modified if `HttpSession.setAttribute()` or `HttpSession.removeAttribute()` was called. You must guarantee that `setAttribute()` is called every time an attribute is changed. This is not a Java EE specification requirement, but it is required for this mode to work properly. `modified-attribute` - Only modified session attributes are stored. For this mode to work properly, you must follow some guidelines, which are explained immediately following this table. Applicable only if the `persistence-type` attribute of the parent session-manager element is `replicated`. Note – The `replicated` persistence type is not supported in GlassFish v3 Prelude.

If the persistenceScope store property is set to modified-attribute, a web module must follow these guidelines:

Call setAttribute() every time the session state is modified.
Make sure there are no cross-references between attributes. The object graph under each distinct attribute key is serialized and stored separately. If there are any object cross references between the objects under each separate key, they are not serialized and deserialized correctly.
Distribute the session state across multiple attributes, or at least between a read-only attribute and a modifiable attribute.

stub-property

Specifies JAX-RPC property values that are set on a javax.xml.rpc.Stub object before it is returned to the web service client. The property names can be any properties supported by the JAX-RPC Stub implementation.

Superelements

port-info (sun-web.xml, sun-ejb-jar.xml)

Subelements

The following table describes subelements for the stub-property element.

Table A–90 stub-property subelements


Element	Required	Description
name	only one	Specifies the name of the entity.
value	only one	Specifies the value of the entity.

Properties

The following table describes properties for the stub-property element.

Table A–91 stub-property properties


Property	Default	Description
`jbi-enabled`	`true`	Determines whether the visibility of this endpoint as a Java Business Integration service is enabled or disabled.

Example

<service-ref>
<service-ref-name>service/FooProxy</service-ref-name>
  <port-info>
	   <service-endpoint-interface>a.FooPort</service-endpoint-interface>
	   <wsdl-port>
		  <namespaceURI>urn:Foo</namespaceURI>
		  <localpart>FooPort</localpart>
	   </wsdl-port>
	   <stub-property>
		  <name>javax.xml.rpc.service.endpoint.address</name>
		  <value>http://localhost:8080/a/Foo</value>
	   </stub-property>
  </port-info>
</service-ref>

sun-ejb-jar

Defines the Enterprise Server specific configuration for an EJB JAR file. This is the root element; there can only be one sun-ejb-jar element in a sun-ejb-jar.xml file. See The sun-ejb-jar.xml File.

Superelements

none

Subelements

The following table describes subelements for the sun-ejb-jar element.

Table A–92 sun-ejb-jar Subelements


Element	Required	Description
security-role-mapping	zero or more	Maps a role in the corresponding Java EE XML file to a user or group.
enterprise-beans	only one	Describes all the runtime properties for an EJB JAR file in the application.

sun-web-app

Defines Enterprise Server specific configuration for a web module. This is the root element; there can only be one sun-web-app element in a sun-web.xml file. See The sun-web.xml File.

Superelements

none

Subelements

The following table describes subelements for the sun-web-app element.

Table A–93 sun-web-app Subelements


Element	Required	Description
context-root	zero or one	Contains the web context root for the web application.
security-role-mapping	zero or more	Maps roles to users or groups in the currently active realm.
servlet	zero or more	Specifies a principal name for a servlet, which is used for the `run-as` role defined in `web.xml`.
idempotent-url-pattern	zero or more	Specifies a URL pattern for idempotent requests.
session-config	zero or one	Specifies session manager, session cookie, and other session-related information.
ejb-ref	zero or more	Maps the absolute JNDI name to the `ejb-ref` in the corresponding Java EE XML file.
resource-ref	zero or more	Maps the absolute JNDI name to the `resource-ref` in the corresponding Java EE XML file.
resource-env-ref	zero or more	Maps the absolute JNDI name to the `resource-env-ref` in the corresponding Java EE XML file.
service-ref	zero or more	Specifies runtime settings for a web service reference.
message-destination-ref	zero or more	Specifies the name of a physical message destination.
cache	zero or one	Configures caching for web application components.
class-loader	zero or one	Specifies class loader configuration information.
jsp-config	zero or one	Specifies JSP configuration information.
locale-charset-info	zero or one	Deprecated. Use the `parameter-encoding` subelement of `sun-web-app` instead.
parameter-encoding	zero or one	Determines the default request character encoding and how the web container decodes parameters from forms according to a hidden field value.
property (with attributes)	zero or more	Specifies a property, which has a name and a value.
message-destination	zero or more	Specifies the name of a logical message destination.
webservice-description	zero or more	Specifies a name and optional publish location for a web service.

Attributes

The following table describes attributes for the sun-web-app element.

Table A–94 sun-web-app Attributes


Attribute	Default	Description
`error-url`	(blank)	(optional) Not implemented. Do not use.
`httpservlet-security-provider`	none	(optional) Specifies the `HttpServlet` message layer provider that the web container's servlet `auth-constraint` processing calls.

Properties

The following table describes properties for the sun-web-app element.

Table A–95 sun-web-app Properties


Property	Default	Description
`allowLinking`	`false`	If `true`, resources in this web application that are symbolic links are served. You can also define this property for a virtual server. Web applications on the virtual server that do not define this property use the virtual server's value. For details, see virtual-server in Sun GlassFish Enterprise Server v3 Prelude Administration Reference. Caution – Setting this property to `true` on Windows systems exposes JSP source code.
`alternatedocroot_n`	none	Specifies an alternate document root (docroot), where `n` is a positive integer that allows specification of more than one. Alternate docroots allow web applications to serve requests for certain resources from outside their own docroot, based on whether those requests match one (or more) of the URI patterns of the web application's alternate docroots. If a request matches an alternate docroot's URI pattern, it is mapped to the alternate docroot by appending the request URI (minus the web application's context root) to the alternate docroot's physical location (directory). If a request matches multiple URI patterns, the alternate docroot is determined according to the following precedence order: Exact match Longest path match Extension match For example, the following properties specify three alternate docroots. The URI pattern of the first alternate docroot uses an exact match, whereas the URI patterns of the second and third alternate docroots use extension and longest path prefix matches, respectively. <property name="alternatedocroot_1" value="from=/my.jpg dir=/srv/images/jpg"/> <property name="alternatedocroot_2" value="from=.jpg dir=/srv/images/jpg"/> <property name="alternatedocroot_3" value="from=/jpg/ dir=/src/images"/> The `value` of each alternate docroot has two components: The first component, `from`, specifies the alternate docroot's URI pattern, and the second component, `dir`, specifies the alternate docroot's physical location (directory). Spaces are allowed in the `dir` component. You can set this property for all the web applications on a specific virtual server. For details, see virtual-server in Sun GlassFish Enterprise Server v3 Prelude Administration Reference.
`valve_n`	none	Specifies a fully qualified class name of a custom valve, where `n` is a positive integer that allows specification of more than one. The valve class must implement the `org.apache.catalina.Valve` interface from Tomcat or previous Enterprise Server releases, or the `org.glassfish.web.valve.GlassFishValve` interface from the current Enterprise Server release. For example: <property name="valve_1" value="org.glassfish.extension.Valve"/> You can set this property for all the web applications on a specific virtual server. For details, see virtual-server in Sun GlassFish Enterprise Server v3 Prelude Administration Reference.
`listener_n`	none	Specifies a fully qualified class name of a custom Catalina listener, where `n` is a positive integer that allows specification of more than one. The listener class must implement the `org.apache.catalina.ContainerListener`, `org.apache.catalina.LifecycleListener`, or `org.apache.catalina.InstanceListener` interface. For example: <property name="listener_1" value="org.glassfish.extension.MyLifecycleListener"/> You can set this property for all the web applications on a specific virtual server. For details, see virtual-server in Sun GlassFish Enterprise Server v3 Prelude Administration Reference.
`crossContextAllowed`	`true`	If `true`, allows this web application to access the contexts of other web applications using the `ServletContext.getContext()`method.
`relativeRedirectAllowed`	`false`	If `true`, allows this web application to send a relative URL to the client using `HttpServletResponse.sendRedirect()`, and instructs the web container not to translate any relative URLs to fully qualified ones.
`reuseSessionID`	`false`	If `true`, sessions generated for this web application use the session ID specified in the request.
`securePagesWithPragma`	`true`	Set this property to `false` to ensure that for this web application file downloads using SSL work properly in Internet Explorer. You can set this property for all the web applications on a specific virtual server. For details, see virtual-server in Sun GlassFish Enterprise Server v3 Prelude Administration Reference.
`singleThreadedServletPoolSize`	`5`	Specifies the maximum number of servlet instances allocated for each `SingleThreadModel` servlet in the web application.
`tempdir`	`domain-dir/generated/app-name` or `domain-dir/generated/module-name`	Specifies a temporary directory for use by this web module. This value is used to construct the value of the `javax.servlet.context.tempdir` context attribute. Compiled JSP files are also placed in this directory.
`useResponseCTForHeaders`	`false`	If `true`, response headers are encoded using the response’s charset instead of the default (UTF-8).