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

Enterprise Edition only. Do not use.

Superelements

ejb (sun-ejb-jar.xml)

checkpointed-methods

Enterprise Edition only. 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 Java EE specification. The behavior of a program that includes such classes or interfaces in its WAR file is undefined.

---

Properties

The following table describes properties for the class-loader element.

Table A–21 class-loader Properties

Property	Default	Description
ignoreHiddenJarFiles	false	If true, specifies that all JAR and ZIP files in the WEB-INF/lib directory that start with a period (.) are ignored by the class loader.

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–22 client-container Subelements

Element	Required	Description
target-server	only one	Specifies the IIOP listener for the target server. A listener is in the form host:port, where the host is an IP address or host name, and the port specifies the port number.
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–23 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–24 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–25 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	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–26 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–27 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 in Sun Java System Application Server Platform Edition 9 Developer’s Guide.

Superelements

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

Subelements

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

Table A–28 cmp-resource Subelements

Element	Required	Description
jndi-name	only one	Specifies the absolute jndi-name of a JDBC 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.
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–29 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–30 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–31 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–32 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–33 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–34 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.

If the parent element is java-web-start-access, this element contains the context root for the Java Web Start enabled application client module. If none is specified, a default is generated; see java-web-start-access.

Superelements

web (sun-application.xml), sun-web-app (sun-web.xml), java-web-start-access (sun-application-client.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–35 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–36 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 Generation Options for CMP in Sun Java System Application Server Platform Edition 9 Developer’s Guide.

Superelements

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

Subelements

none - contains data