Sun Java System Application Server Enterprise Edition 8.2 Developer's 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–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:

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:

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