Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Developer's Guide

- Previous: R
- Next: T

# 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–95 `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

Specifies the file that contains a description of the database schema to which the beans in this `sun-cmp-mappings.xml` file are mapped. If this element is empty, the database schema file is automatically generated at deployment time. Otherwise, the `schema` element names a `.dbschema` file with a pathname relative to the directory containing the `sun-cmp-mappings.xml` file, but without the `.dbschema` extension. See Automatic Database Schema Capture.

### Superelements

sun-cmp-mapping (`sun-cmp-mappings.xml`)

### Subelements

none - contains data

### Examples

    <schema/> <!-- use automatic schema generation -->

    <schema>CompanySchema</schema> <!-- use "CompanySchema.dbschema" -->

## schema-generator-properties

Specifies field-specific column attributes in `property` subelements.

### Superelements

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

### Subelements

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

Table A–96 `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–97 `schema-generator-properties` Properties

Property | Default | Description
--- | --- | ---
`use-unique-table-names` | `false` | Specifies that generated table names are unique within each application server domain. This property can be overridden during deployment. See Table 7–4.
    bean-name.field-name.attribute
| none | Defines a column attribute. For attribute descriptions, see Table A–98.

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

Table A–98 `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>

## secondary-table

Specifies a bean’s secondary table(s).

### Superelements

entity-mapping (`sun-cmp-mappings.xml`)

### Subelements

The following table describes subelements for the `secondary-table` element.

Table A–99 `secondary table` Subelements

Element | Required | Description
--- | --- | ---
table-name | only one | Specifies the name of a database table.
column-pair | one or more | Specifies the pair of columns that determine the relationship between two database tables.

## security

Defines the SSL security configuration for IIOP/SSL communication with the target server.

### Superelements

target-server (`sun-acc.xml`)

### Subelements

The following table describes subelements for the `security` element.

Table A–100 `security` Subelements

Element | Required | Description
--- | --- | ---
ssl | only one | Specifies the SSL processing parameters.
cert-db | only one | Not implemented. Included for backward compatibility only.

## security-role-mapping

Maps roles to users or groups in the currently active realm. See Realm Configuration.

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-application (`sun-application.xml`), 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–101 `security-role-mapping` Subelements

Element | Required | Description
--- | --- | ---
role-name | only one | Contains the `role-name` in the `security-role` element of the corresponding J2EE 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`, `sun-application-client.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`, `sun-application-client.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`, `sun-application-client.xml`); webservice-endpoint (`sun-web.xml`, `sun-ejb-jar.xml`)

### Subelements

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

Table A–102 `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 J2EE deployment descriptor

### Superelements

sun-web-app (`sun-web.xml`), ejb (`sun-ejb-jar.xml`), sun-application-client (`sun-application-client.xml`)

### Subelements

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

Table A–103 `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`, `sun-application-client.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–104 `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 application.

### Superelements

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

### Subelements

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

Table A–105 `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–106 `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–107 `session-manager` Attributes

Attribute | Default | Description
--- | --- | ---
`persistence-type` | `memory` | (optional) Specifies the session persistence mechanism. Allowed values are `memory` ,`file`, and `ha` . For production environments that require session persistence, use `ha`.

## session-properties

Specifies session properties.

### Superelements

session-config (`sun-web.xml`)

### Subelements

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

Table A–108 `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–109 `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.

## ssl

Defines SSL processing parameters.

### Superelements

security (`sun-acc.xml`)

### Subelements

none

### Attributes

The following table describes attributes for the `SSL` element.

Table A–110 `ssl attributes`

Attribute | Default | Description
--- | --- | ---
`cert-nickname` | none | (optional) The nickname of the server certificate in the certificate database or the PKCS#11 token. In the certificate, the name format is tokenname`:`nickname. Including the tokenname`:` part of the name in this attribute is optional.
`ssl2-enabled` | `false` | (optional) Determines whether SSL2 is enabled.
`ssl2-ciphers` | none | (optional) A space-separated list of the SSL2 ciphers used with the prefix + to enable or - to disable. For example, `+rc4`. Allowed values are `rc4, rc4export, rc2, rc2export, idea, des, desede3`.
`ssl3-enabled` | `true` | (optional) Determines whether SSL3 is enabled.
`ssl3-tls-ciphers` | none | (optional) A space-separated list of the SSL3 ciphers used, with the prefix + to enable or - to disable, for example +`rsa_des_sha`. Allowed SSL3 values are `rsa_rc4_128_md5, , rsa_des_sha, rsa_rc4_40_md5, rsa_rc2_40_md5, rsa_null_md5. Allowed TLS values are rsa_des_56_sha, rsa_rc4_56_sha`.
`tls-enabled` | `true` | (optional) Determines whether TLS is enabled.
`tls-rollback-enabled` | `true` | (optional) Determines whether TLS rollback is enabled. Enable TLS rollback for Microsoft Internet Explorer 5.0 and 5.5.

## 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.

### 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–111 `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–112 `store-properties` Properties

Property | Default | Description
--- | --- | ---
`directory` | domain-dir`/generated/jsp/j2ee-apps/`app-name`/`app-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 application. 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 application. `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 J2EE 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 `ha`.

If the `persistenceScope` store property is set to `modified-attribute`, a web application 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`, `sun-application-client.xml`)

### Subelements

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

Table A–113 `stub-property` subelements

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

### 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-application

Defines the Application Server specific configuration for an application. This is the root element; there can only be one `sun-application` element in a `sun-application.xml` file. See The sun-application.xml File.

### Superelements

none

### Subelements

The following table describes subelements for the `sun-application` element.

Table A–114 `sun-application` Subelements

Element | Required | Description
--- | --- | ---
web | zero or more | Specifies the application’s web tier configuration.
pass-by-reference | zero or one | Determines whether EJB modules use pass-by-value or pass-by-reference semantics.
unique-id | zero or one | Contains the unique ID for the application.
security-role-mapping | zero or more | Maps a role in the corresponding J2EE XML file to a user or group.
realm | zero or one | Specifies an authentication realm.

## sun-application-client

Defines the Application Server specific configuration for an application client. This is the root element; there can only be one `sun-application-client` element in a `sun-application-client.xml` file. See The sun-application-client.xml file.

### Superelements

none

### Subelements

The following table describes subelements for the `sun-application-client` element.

Table A–115 `sun-application-client` subelements

Element | Required | Description
--- | --- | ---
ejb-ref | zero or more | Maps the absolute JNDI name to the `ejb-ref` in the corresponding J2EE XML file.
resource-ref | zero or more | Maps the absolute JNDI name to the `resource-ref` in the corresponding J2EE XML file.
resource-env-ref | zero or more | Maps the absolute JNDI name to the `resource-env-ref` in the corresponding J2EE XML file.
service-ref | zero or more | Specifies runtime settings for a web service reference.
message-destination | zero or more | Specifies the name of a logical message destination.

## sun-cmp-mapping

Specifies beans mapped to a particular database schema.

Note –

A bean cannot be related to a bean that maps to a different database schema, even if the beans are deployed in the same EJB JAR file.

### Superelements

sun-cmp-mappings (`sun-cmp-mappings.xml`)

### Subelements

The following table describes subelements for the `sun-cmp-mapping` element.

Table A–116 `sun-cmp-mapping` Subelements

Element | Required | Description
--- | --- | ---
schema | only one | Specifies the file that contains a description of the database schema.
entity-mapping | one or more | Specifies the mapping of a bean to database columns.

## sun-cmp-mappings

Defines the Application Server specific CMP mapping configuration for an EJB JAR file. This is the root element; there can only be one `sun-cmp-mappings` element in a `sun-cmp-mappings.xml` file. See The sun-cmp-mappings.xml File.

### Superelements

none

### Subelements

The following table describes subelements for the `sun-cmp-mappings` element.

Table A–117 `sun-cmp-mappings` Subelements

Element | Required | Description
--- | --- | ---
sun-cmp-mapping | one or more | Specifies beans mapped to a particular database schema.

## sun-ejb-jar

Defines the Application 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–118 `sun-ejb-jar` Subelements

Element | Required | Description
--- | --- | ---
security-role-mapping | zero or more | Maps a role in the corresponding J2EE 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 Application 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–119 `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 J2EE XML file.
resource-ref | zero or more | Maps the absolute JNDI name to the `resource-ref` in the corresponding J2EE XML file.
resource-env-ref | zero or more | Maps the absolute JNDI name to the `resource-env-ref` in the corresponding J2EE XML file.
service-ref | zero or more | Specifies runtime settings for a web service reference.
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.
property (with attributes) | zero or more | Specifies a property, which has a name and a value.
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.
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–120 `sun-web-app` Attributes

Attribute | Default | Description
--- | --- | ---
`error-url` | (blank) | (optional) Specifies a redirect URL in case of an error.

### Properties

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

Table A–121 `sun-web-app` Properties

Property | Default | Description
--- | --- | ---
`allowLinking` | `true` | If `true`, resources in this web application that are symbolic links are served.
`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.
`singleThreadedServletPoolSize` | `5` | Specifies the maximum number of servlet instances allocated for each `SingleThreadModel` servlet in the web application.
`tempdir` | domain-dir`/generated/j2ee-apps/`app-name or domain-dir`/generated/j2ee-modules/`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).

- Previous: R
- Next: T

- © 2010, Oracle Corporation and/or its affiliates