Sun Java System Application Server Enterprise Edition 8.2 Developer's Guide

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.4/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.


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

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:

Superelements

cache, cache-helper, class-loader, cookie-properties, default-helper, manager-properties, session-properties, store-properties, sun-web-app (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–82 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–83 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:

Superelements

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

Subelements

The following table describes subelements for the property element.

Table A–84 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–85 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 or a variable. 

Attributes

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

Table A–86 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.