Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Developer's Guide

- Previous: B
- Next: D

# C

## cache

Configures caching for web application components.

### Superelements

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

### Subelements

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

Table A–9 `cache` Subelements

Element | Required | Description
--- | --- | ---
cache-helper | zero or more | Specifies a custom class that implements the `CacheHelper` interface.
default-helper | zero or one | Allows you to change the properties of the default, built-in cache-helper class.
property (with attributes) | zero or more | Specifies a cache property, which has a name and a value.
cache-mapping | zero or more | Maps a URL pattern or a servlet name to its cacheability constraints.

### Attributes

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

Table A–10 `cache` Attributes

Attribute | Default | Description
--- | --- | ---
`max-entries` | `4096` | (optional) Specifies the maximum number of entries the cache can contain. Must be a positive integer.
`timeout-in-seconds` | `30` | (optional) Specifies the maximum amount of time in seconds that an entry can remain in the cache after it is created or refreshed. Can be overridden by a timeout element.
`enabled` | `true` | (optional) Determines whether servlet and JSP caching is enabled.

### Properties

The following table describes properties for the `cache` element.

Table A–11 `cache` Properties

Property | Default | Description
--- | --- | ---
`cacheClassName` | `com.sun.appserv.web.cache.LruCache` | Specifies the fully qualified name of the class that implements the cache functionality. See Cache Class Names for possible values.
`MultiLRUSegmentSize` | `4096` | Specifies the number of entries in a segment of the cache table that should have its own LRU (least recently used) list. Applicable only if `cacheClassName` is set to `com.sun.appserv.web.cache.MultiLruCache`.
`MaxSize` | unlimited; `Long.MAX_VALUE` | Specifies an upper bound on the cache memory size in bytes (KB or MB units). Example values are `32 KB` or `2 MB`. Applicable only if `cacheClassName` is set to `com.sun.appserv.web.cache.BoundedMultiLruCache`.

### Cache Class Names

The following table lists possible values of the `cacheClassName` property.

Table A–12 `cacheClassName` Values

Value | Description
--- | ---
`com.sun.appserv.web.cache.LruCache` | A bounded cache with an LRU (least recently used) cache replacement policy.
`com.sun.appserv.web.cache.BaseCache` | An unbounded cache suitable if the maximum number of entries is known.
`com.sun.appserv.web.cache.MultiLruCache` | A cache suitable for a large number of entries (>4096). Uses the `MultiLRUSegmentSize` property.
`com.sun.appserv.web.cache.BoundedMultiLruCache` | A cache suitable for limiting the cache size by memory rather than number of entries. Uses the `MaxSize` property.

## cache-helper

Specifies a class that implements the `com.sun.appserv.web.cache.``CacheHelper` interface.

### Superelements

cache (`sun-web.xml`)

### Subelements

The following table describes subelements for the `cache-helper` element.

Table A–13 `cache-helper` Subelements

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

### Attributes

The following table describes attributes for the `cache-helper` element.

Table A–14 `cache-helper` Attributes

Attribute | Default | Description
--- | --- | ---
`name` | `default` | Specifies a unique name for the helper class, which is referenced in the cache-mapping element.
`class-name` | none | Specifies the fully qualified class name of the cache helper, which must implement the `com.sun.appserv.web.CacheHelper` interface.

## cache-helper-ref

Specifies the `name` of the cache-helper used by the parent cache-mapping element.

### Superelements

cache-mapping (`sun-web.xml`)

### Subelements

none - contains data

## cache-idle-timeout-in-seconds

Specifies the maximum time that a bean can remain idle in the cache. After this amount of time, the container can passivate this bean. A value of `0` specifies that beans never become candidates for passivation. Default is 600.

Applies to stateful session beans and entity beans.

### Superelements

bean-cache (`sun-ejb-jar.xml`)

### Subelements

none - contains data

## cache-mapping

Maps a URL pattern or a servlet name to its cacheability constraints.

### Superelements

cache (`sun-web.xml`)

### Subelements

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

Table A–15 `cache-mapping` Subelements

Element | Required | Description
--- | --- | ---
servlet-name | requires one `servlet-name` or `url-pattern` | Contains the name of a servlet.
url-pattern | requires one `servlet-name` or `url-pattern` | Contains a servlet URL pattern for which caching is enabled.
cache-helper-ref | required if `dispatcher`, `timeout`, `refresh-field`, `http-method`, `key-field`, and `constraint-field` are not used | Contains the `name` of the cache-helper used by the parent `cache-mapping` element.
dispatcher | zero or one if `cache-helper-ref` is not used | Contains a comma-separated list of `RequestDispatcher` methods for which caching is enabled.
timeout | zero or one if `cache-helper-ref` is not used | Contains the cache-mapping specific maximum amount of time in seconds that an entry can remain in the cache after it is created or refreshed.
refresh-field | zero or one if `cache-helper-ref` is not used | Specifies a field that gives the application component a programmatic way to refresh a cached entry.
http-method | zero or more if `cache-helper-ref` is not used | Contains an HTTP method that is eligible for caching.
key-field | zero or more if `cache-helper-ref` is not used | Specifies a component of the key used to look up and extract cache entries.
constraint-field | zero or more if `cache-helper-ref` is not used | Specifies a cacheability constraint for the given `url-pattern` or `servlet-name`.

## call-property

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. The property names can be any properties supported by the JAX-RPC `Call` implementation.

### Superelements

port-info, service-ref (`sun-web.xml`, `sun-ejb-jar.xml`, `sun-application-client.xml`)

### Subelements

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

Table A–16 `call-property` subelements

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

## caller-propagation

Specifies whether the target accepts propagated caller identities. The values are `NONE`, `SUPPORTED`, or `REQUIRED`.

### Superelements

sas-context (`sun-ejb-jar.xml`)

### Subelements

none - contains data

## cert-db

Not implemented. Included for backward compatibility only. Attribute values are ignored.

### Superelements

security (`sun-acc.xml`)

### Subelements

none

### Attributes

The following table describes attributes for the `cert-db` element.

Table A–17 `cert-db` attributes

Attribute | Default | Description
--- | --- | ---
`path` | none | Specifies the absolute path of the certificate database.
`password` | none | Specifies the password to access the certificate database.

## check-all-at-commit

This element is not implemented. Do not use.

### Superelements

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

## check-modified-at-commit

Checks concurrent modification of fields in modified beans at commit time.

### Superelements

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

### Subelements

none - element is present or absent

## check-version-of-accessed-instances

Checks the version column of the modified beans.

Version consistency allows the bean state to be cached between transactions instead of read from a database. The bean state is verified by primary key and version column values. This occurs during a custom query (for dirty instances only) or commit (for both clean and dirty instances).

The version column must be a numeric type, and must be in the primary table. You must provide appropriate update triggers for this column.

### Superelements

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

### Subelements

The following table describes subelements for the `check-version-of-accessed-instances` element.

Table A–18 `check-version-of-accessed-instances` Subelements

Element | Required | Description
--- | --- | ---
column-name | only one | Specifies the name of the version column.

## checkpoint-at-end-of-method

Not available. Do not use.

### Superelements

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

## checkpointed-methods

Not available. Do not use.

### Superelements

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

## class-loader

Configures the class loader for the web module.

### Superelements

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

### Subelements

The following table describes subelements for the `class-loader` element.

Table A–19 `class-loader` Subelements

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

### Attributes

The following table describes attributes for the `class-loader` element.

Table A–20 `class-loader` Attributes

Attribute | Default | Description
--- | --- | ---
`extra-class-path` | null | (optional) Specifies additional classpath settings for this web module.
`delegate` | `true` | (optional) If `true`, the web module follows the standard class loader delegation model and delegates to its parent class loader first before looking in the local class loader. You must set this to `true` for a web application that accesses EJB components or that acts as a web service client or endpoint. If `false`, the web module follows the delegation model specified in the Servlet specification and looks in its class loader before looking in the parent class loader. It’s safe to set this to `false` only for a web module that does not interact with any other modules.
`dynamic-reload-interval` |  | (optional) Not implemented. Included for backward compatibility with previous Sun Java System Web Server versions.

Note –

If the `delegate` element is set to `false`, the class loader delegation behavior complies with the Servlet 2.4 specification, section 9.7.2. If set to its default value of `true`, classes and resources residing in container-wide library JAR files are loaded in preference to classes and resources packaged within the WAR file.

Portable programs that use this element should not be packaged with any classes or interfaces that are a part of the J2EE specification. The behavior of a program that includes such classes or interfaces in its WAR file is undefined.

## client-container

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

### Superelements

none

### Subelements

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

Table A–21 `client-container` Subelements

Element | Required | Description
--- | --- | ---
target-server | only one | Specifies the IIOP listener configuration of the target server.
auth-realm | zero or one | Specifies the optional configuration for JAAS authentication realm.
client-credential | zero or one | Specifies the default client credential that is sent to the server.
log-service | zero or one | Specifies the default log file and the severity level of the message.
message-security-config | zero or more | Specifies configurations for message security providers.
property (with attributes) | zero or more | Specifies a property, which has a name and a value.

### Attributes

The following table describes attributes for the `client-container` element.

Table A–22 `client-container` Attributes

Attribute | Default | Description
--- | --- | ---
`send-password` | `true` | If `true`, specifies that client authentication credentials must be sent to the server. Without authentication credentials, all access to protected EJB components results in exceptions.

## client-credential

Default client credentials that are sent to the server. If this element is present, the credentials are automatically sent to the server, without prompting the user for the user name and password on the client side.

### Superelements

client-container (`sun-acc.xml`)

### Subelements

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

Table A–23 `client-credential` subelement

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

### Attributes

The following table describes attributes for the `client-credential` element.

Table A–24 `client-credential` attributes

Attribute | Default | Description
--- | --- | ---
`user-name` | none | The user name used to authenticate the Application client container.
`password` | none | The password used to authenticate the Application client container.
`realm` | the default realm for the domain | (optional) The realm (specified by name) where credentials are to be resolved.

## cmp

Describes runtime information for a CMP entity bean object for EJB 1.1 and EJB 2.1 beans.

### Superelements

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

### Subelements

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

Table A–25 `cmp` Subelements

Element | Required | Description
--- | --- | ---
mapping-properties | zero or one | This element is not implemented.
is-one-one-cmp | zero or one | This element is not implemented.
one-one-finders | zero or one | Describes the finders for CMP 1.1 beans.
prefetch-disabled | zero or one | Disables prefetching of entity bean states for the specified query methods.

## cmp-field-mapping

The `cmp-field-mapping` element associates a field with one or more columns to which it maps. The column can be from a bean’s primary table or any defined secondary table. If a field is mapped to multiple columns, the column listed first in this element is used as a source for getting the value from the database. The columns are updated in the order they appear. There is one `cmp-field-mapping` element for each `cmp-field` element defined in the `ejb-jar.xml` file.

### Superelements

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

### Subelements

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

Table A–26 `cmp-field-mapping` Subelements

Element | Required | Description
--- | --- | ---
field-name | only one | Specifies the Java identifier of a field. This identifier must match the value of the `field-name` subelement of the `cmp-field` that is being mapped.
column-name | one or more | Specifies the name of a column from the primary table, or the qualified table name (TABLE.COLUMN) of a column from a secondary or related table.
read-only | zero or one | Specifies that a field is read-only.
fetched-with | zero or one | Specifies the fetch group for this CMP field’s mapping.

## cmp-resource

Specifies the database to be used for storing CMP beans. For more information about this element, see Configuring the CMP Resource.

### Superelements

enterprise-beans (`sun-ejb-jar.xml`)

### Subelements

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

Table A–27 `cmp-resource` Subelements

Element | Required | Description
--- | --- | ---
jndi-name | only one | Specifies the absolute `jndi-name` of a JDBC resource or Persistence Manager resource.
default-resource-principal | zero or one | Specifies the default runtime bindings of a resource reference.
property (with subelements) | zero or more | Specifies a property name and value. Used to configure `PersistenceManagerFactory` properties if the `jndi-name` subelement refers to a JDBC resource.
create-tables-at-deploy | zero or one | If `true`, specifies that database tables are created for beans that are automatically mapped by the EJB container.
drop-tables-at-undeploy | zero or one | If `true`, specifies that database tables that were automatically created when the bean(s) were last deployed are dropped when the bean(s) are undeployed.
database-vendor-name | zero or one | Specifies the name of the database vendor for which tables can be created.
schema-generator-properties | zero or one | Specifies field-specific type mappings and allows you to set the `use-unique-table-names` property.

## cmr-field-mapping

A container-managed relationship field has a name and one or more column pairs that define the relationship. There is one `cmr-field-mapping` element for each `cmr-field` element in the `ejb-jar.xml` file. A relationship can also participate in a fetch group.

### Superelements

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

### Subelements

The following table describes subelements for the `cmr-field-mapping` element.

Table A–28 `cmr-field-mapping` Subelements

Element | Required | Description
--- | --- | ---
cmr-field-name | only one | Specifies the Java identifier of a field. Must match the value of the `cmr-field-name` subelement of the `cmr-field` that is being mapped.
column-pair | one or more | Specifies the pair of columns that determine the relationship between two database tables.
fetched-with | zero or one | Specifies the fetch group for this CMR field’s relationship.

## cmr-field-name

Specifies the Java identifier of a field. Must match the value of the `cmr-field-name` subelement of the `cmr-field` element in the `ejb-jar.xml` file.

### Superelements

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

### Subelements

none - contains data

## cmt-timeout-in-seconds

Overrides the Transaction Timeout setting of the Transaction Service for an individual bean. The default value, `0`, specifies that the default Transaction Service timeout is used. If positive, this value is used for all methods in the bean that start a new container-managed transaction. This value is not used if the bean joins a client transaction.

### Superelements

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

### Subelements

none - contains data

## column-name

Specifies the name of a column from the primary table, or the qualified table name (TABLE.COLUMN) of a column from a secondary or related table.

### Superelements

check-version-of-accessed-instances, cmp-field-mapping, column-pair (`sun-cmp-mappings.xml`)

### Subelements

none - contains data

## column-pair

Specifies the pair of columns that determine the relationship between two database tables. Each `column-pair` must contain exactly two `column-name` subelements, which specify the column’s names. The first `column-name` element names the table that this bean is mapped to, and the second `column-name` names the column in the related table.

### Superelements

cmr-field-mapping, secondary-table (`sun-cmp-mappings.xml`)

### Subelements

The following table describes subelements for the `column-pair` element.

Table A–29 `column-pair` Subelements

Element | Required | Description
--- | --- | ---
column-name | two | Specifies the name of a column from the primary table, or the qualified table name (TABLE.COLUMN) of a column from a secondary or related table.

## commit-option

Specifies the commit option used on transaction completion. Valid values for the Application Server are `B` or `C`. Default value is `B`. Applies to entity beans.

Note –

Commit option A is not supported for this Application Server release.

### Superelements

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

### Subelements

none - contains data

## confidentiality

Specifies if the target supports privacy-protected messages. The values are `NONE`, `SUPPORTED`, or `REQUIRED`.

### Superelements

transport-config (`sun-ejb-jar.xml`)

### Subelements

none - contains data

## consistency

Specifies container behavior in guaranteeing transactional consistency of the data in the bean.

### Superelements

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

### Subelements

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

Table A–30 `consistency` Subelements

Element | Required | Description
--- | --- | ---
none | exactly one subelement is required | No consistency checking occurs.
check-modified-at-commit | exactly one subelement is required | Checks concurrent modification of fields in modified beans at commit time.
lock-when-loaded | exactly one subelement is required | Obtains an exclusive lock when the data is loaded.
check-all-at-commit |  | This element is not implemented. Do not use.
lock-when-modified |  | This element is not implemented. Do not use.
check-version-of-accessed-instances | exactly one subelement is required | Checks the version column of the modified beans.

## constraint-field

Specifies a cacheability constraint for the given url-pattern or servlet-name.

All `constraint-field` constraints must pass for a response to be cached. If there are `value` constraints, at least one of them must pass.

### Superelements

cache-mapping (`sun-web.xml`)

### Subelements

The following table describes subelements for the `constraint-field` element.

Table A–31 `constraint-field` Subelements

Element | Required | Description
--- | --- | ---
constraint-field-value | zero or more | Contains a value to be matched to the input parameter value.

### Attributes

The following table describes attributes for the `constraint-field` element.

Table A–32 `constraint-field` Attributes

Attribute | Default | Description
--- | --- | ---
`name` | none | Specifies the input parameter name.
`scope` | `request.parameter` | (optional) Specifies the scope from which the input parameter is retrieved. Allowed values are `context.attribute`, `request.header`, `request.parameter`, `request.cookie`, `request.attribute`, and `session.attribute`.
`cache-on-match` | `true` | (optional) If `true`, caches the response if matching succeeds. Overrides the same attribute in a constraint-field-value subelement.
`cache-on-match-failure` | `false` | (optional) If `true`, caches the response if matching fails. Overrides the same attribute in a constraint-field-value subelement.

## constraint-field-value

Specifies a value to be matched to the input parameter value. The matching is case sensitive. For example:

    <value match-expr="in-range">1-60</value>

### Superelements

constraint-field (`sun-web.xml`)

### Subelements

none - contains data

### Attributes

The following table describes attributes for the `constraint-field-value` element.

Table A–33 `constraint-field-value` Attributes

Attribute | Default | Description
--- | --- | ---
`match-expr` | `equals` | (optional) Specifies the type of comparison performed with the value. Allowed values are `equals`, `not-equals`, `greater`, `lesser`, and `in-range`. If `match-expr` is `greater` or `lesser`, the value must be a number. If `match-expr` is `in-range`, the value must be of the form n1`-`n2, where n1 and n2 are numbers.
`cache-on-match` | `true` | (optional) If `true`, caches the response if matching succeeds.
`cache-on-match-failure` | `false` | (optional) If `true`, caches the response if matching fails.

## context-root

Contains the web context root for the application or web application. Overrides the corresponding element in the `application``.xml` or `web``.xml` file.

### Superelements

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

### Subelements

none - contains data

## cookie-properties

Specifies session cookie properties.

### Superelements

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

### Subelements

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

Table A–34 `cookie-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 `cookie-properties` element.

Table A–35 `cookie-properties` Properties

Property | Default | Description
--- | --- | ---
`cookiePath` | Context path at which the web module is installed. | Specifies the pathname that is set when the cookie is created. The browser sends the cookie if the pathname for the request contains this pathname. If set to `/` (slash), the browser sends cookies to all URLs served by the Application Server. You can set the path to a narrower mapping to limit the request URLs to which the browser sends cookies.
`cookieMaxAgeSeconds` | `-1` | Specifies the expiration time (in seconds) after which the browser expires the cookie.
`cookieDomain` | (unset) | Specifies the domain for which the cookie is valid.
`cookieComment` | `Sun Java System Application Server Session Tracking Cookie` | Specifies the comment that identifies the session tracking cookie in the cookie file. Applications can provide a more specific comment for the cookie.

## create-tables-at-deploy

Specifies whether database tables are created for beans that are automatically mapped by the EJB container. If `true`, creates tables in the database. If `false` (the default if this element is not present), does not create tables.

This element can be overridden during deployment. See Table 7–4.

### Superelements

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

### Subelements

none - contains data

- Previous: B
- Next: D

- © 2010, Oracle Corporation and/or its affiliates