P

parameter-encoding

Specifies the default request character encoding and how the web container decodes parameters from forms according to a hidden field value.

If both the sun-web-app and locale-charset-info elements have parameter-encoding subelements, the subelement of sun-web-app takes precedence. For encodings, see http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html.

Superelements

locale-charset-info, sun-web-app (sun-web.xml)

Subelements

none

Attributes

The following table describes attributes for the parameter-encoding element.

Table A–78 parameter-encoding Attributes

Attribute	Default	Description
form-hint-field	none	(optional) The name of the hidden field in the form. This field specifies the character encoding the web container uses for request.getParameter and request.getReader calls when the charset is not set in the request’s content-type header.
default-charset	ISO-8859-1	(optional) The default request character encoding.

pass-by-reference

Specifies the passing method used by a servlet or enterprise bean calling a remote interface method in another bean that is colocated within the same process.

• If false (the default if this element is not present), this application uses pass-by-value semantics.

• If true, this application uses pass-by-reference semantics.

---

Note –

The pass-by-reference element only applies to remote calls. As defined in the EJB 2.1 specification, section 5.4, calls to local interfaces use pass-by-reference semantics.

If the pass-by-reference element is set to its default value of false, the passing semantics for calls to remote interfaces comply with the EJB 2.1 specification, section 5.4. If set to true, remote calls involve pass-by-reference semantics instead of pass-by-value semantics, contrary to this specification.

Portable programs cannot assume that a copy of the object is made during such a call, and thus that it’s safe to modify the original. Nor can they assume that a copy is not made, and thus that changes to the object are visible to both caller and callee. When this element is set to true, parameters and return values should be considered read-only. The behavior of a program that modifies such parameters or return values is undefined.

---

When a servlet or enterprise bean calls a remote interface method in another bean that is colocated within the same process, by default the Application Server makes copies of all the call parameters in order to preserve the pass-by-value semantics. This increases the call overhead and decreases performance.

However, if the calling method does not change the object being passed as a parameter, it is safe to pass the object itself without making a copy of it. To do this, set the pass-by-reference value to true.

The setting of this element in the sun-application.xml file applies to all EJB modules in the application. For an individually deployed EJB module, you can set the same element in the sun-ejb-jar.xml file. If pass-by-reference is used at both the bean and application level, the bean level takes precedence.

Superelements

sun-application (sun-application.xml), ejb (sun-ejb-jar.xml)

Subelements

none - contains data

password

Specifies the password for the principal.

Superelements

default-resource-principal (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)

Subelements

none - contains data

pm-descriptors

This element and its subelements are deprecated. Do not use.

Superelements

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

pool-idle-timeout-in-seconds

Specifies the maximum time, in seconds, that a bean instance is allowed to remain idle in the pool. When this timeout expires, the bean instance in a pool becomes a candidate for passivation or deletion. This is a hint to the server. A value of 0 specifies that idle beans remain in the pool indefinitely. Default value is 600.

Applies to stateless session beans, entity beans, and message-driven beans.

---

Note –

For a stateless session bean or a message-driven bean, the bean is removed (garbage collected) when the timeout expires.

---

Superelements

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

Subelements

none - contains data

port-component-name

Specifies a unique name for a port component within a web or EJB module.

Superelements

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

Subelements

none - contains data

port-info

Specifies information for a port within a web service reference.

Either a service-endpoint-interface or a wsdl-port or both must be specified. If both are specified, wsdl-port specifies the port that the container chooses for container-managed port selection.

The same wsdl-port value must not appear in more than one port-info element within the same service-ref.

If a service-endpoint-interface is using container-managed port selection, its value must not appear in more than one port-info element within the same service-ref.

Superelements

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

Subelements

The following table describes subelements for the port-info element.

Table A–79 port-info subelements

Element	Required	Description
service-endpoint-interface	zero or one	Specifies the web service reference name relative to java:comp/env.
wsdl-port	zero or one	Specifies the WSDL port.
stub-property	zero or more	Specifies JAX-RPC property values that are set on a javax.xml.rpc.Stub object before it is returned to the web service client.
call-property	zero or more	Specifies JAX-RPC property values that are set on a javax.xml.rpc.Call object before it is returned to the web service client.
message-security-binding	zero or one	Specifies a custom authentication provider binding.

prefetch-disabled

Disables prefetching of entity bean states for the specified query methods. Container-managed relationship fields are prefetched if their fetched-with element is set to default.

Superelements

cmp (sun-ejb-jar.xml)

Subelements

The following table describes subelements for the prefetch-disabled element.

Table A–80 prefetch-disabled Subelements

Element	Required	Description
query-method	one or more	Specifies a query method.

principal

Defines a node that specifies a user name on the platform.

Superelements

ejb (sun-ejb-jar.xml)

Subelements

The following table describes subelements for the principal element.

Table A–81 principal Subelements

Element	Required	Description
name	only one	Specifies the name of the user.

principal-name

Contains the principal (user) name.

In an enterprise bean, specifies the principal (user) name that has the run-as role specified.

Superelements

security-role-mapping (sun-application.xml, sun-web.xml, sun-ejb-jar.xml), servlet (sun-web.xml)

Subelements

none - contains data

Attributes

The following table describes attributes for the principal-name element.

Table A–82 principal-name Attributes

Attribute	Default	Description
class-name	com.sun.enterprise.deployment.PrincipalImpl	(optional) Specifies the custom principal implementation class corresponding to the named principal.

property (with attributes)

Specifies the name and value of a property. A property adds configuration information to its parent element that is one or both of the following:

• Optional with respect to Application Server

• Needed by a system or object that Application Server doesn’t have knowledge of, such as an LDAP server or a Java class

Superelements

cache, cache-helper, class-loader, cookie-properties, default-helper, manager-properties, session-properties, store-properties, sun-web-app, webservice-endpoint (sun-web.xml); auth-realm, client-container, client-credential, log-service, provider-config (sun-acc.xml)

Subelements

The following table describes subelements for the property element.

Table A–83 property Subelements

Element	Required	Description
description	zero or one	Specifies an optional text description of a property.

---

Note –

The property element in the sun-acc.xml file has no subelements.

---

Attributes

The following table describes attributes for the property element.

Table A–84 property Attributes

Attribute	Default	Description
name	none	Specifies the name of the property.
value	none	Specifies the value of the property.

Example

<property name="reapIntervalSeconds" value="20" />

property (with subelements)

Specifies the name and value of a property. A property adds configuration information to its parent element that is one or both of the following:

• Optional with respect to Application Server

• Needed by a system or object that Application Server doesn’t have knowledge of, such as an LDAP server or a Java class

Superelements

cmp-resource, schema-generator-properties, webservice-endpoint (sun-ejb-jar.xml)

Subelements

The following table describes subelements for the property element.

Table A–85 property subelements

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

Example

<property>
   <name>use-unique-table-names</name>
   <value>true</value>
</property>

provider-config

Specifies a configuration for one message security provider.

Although the request-policy and response-policy subelements are optional, the provider-config element does nothing if they are not specified.

Use property subelements to configure provider-specific properties. Property values are passed to the provider when its initialize method is called.

Superelements

message-security-config (sun-acc.xml)

Subelements

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

Table A–86 provider-config Subelements

Element	Required	Description
request-policy	zero or one	Defines the authentication policy requirements of the authentication provider’s request processing.
response-policy	zero or one	Defines the authentication policy requirements of the authentication provider’s response processing.
property (with attributes)	zero or more	Specifies a property, which has a name and a value.

Attributes

The following table describes attributes for the provider-config element.

Table A–87 provider-config Attributes

Attribute	Default	Description
provider-id	none	Specifies the provider ID.
provider-type	none	Specifies whether the provider is a client, server, or client-server authentication provider.
class-name	none	Specifies the Java implementation class of the provider. Client authentication providers must implement the com.sun.enterprise.security.jauth.ClientAuthModule interface. Server authentication providers must implement the com.sun.enterprise.security.jauth.ServerAuthModule interface. Client-server providers must implement both interfaces.