Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Developer's Guide

- Previous: O
- Next: Q

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

- 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

## 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 (`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:

- 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 (`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.

- Previous: O
- Next: Q

- © 2010, Oracle Corporation and/or its affiliates