BEA WebLogic Server 9.0 API Reference

weblogic.jndi
Class Environment

java.lang.Object
  weblogic.jndi.Environment

All Implemented Interfaces:

Externalizable, Serializable

public final class Environment

extends Object

implements Externalizable

The Environment class represents the properties used to create an initial Context. It provides type-safe methods to set and get common JNDI properties and a convenient way to create a new initial Context. Although this class uses WLInitialContextFactory as its default factory, it may be used to create an initial Context using any legal factory.

Here's an example of how to create an initial context:

   Hashtable props = new Hashtable();
   props.put(Context.INITIAL_CONTEXT_FACTORY,
             "weblogic.jndi.WLInitialContextFactory");
   props.put(Context.PROVIDER_URL,         "t3://weblogic:7001");
   props.put(Context.SECURITY_PRINCIPAL,   "fred");
   props.put(Context.SECURITY_CREDENTIALS, "seafood");
   Context ctx = new InitialContext(props);

This code can be rewritten using an Environment object as illustrated here:

  Environment env = new Environment();
   env.setProviderUrl("t3://weblogicServer:7001");
   env.setSecurityPrincipal("fred");
   env.setSecurityCredentials("seafood");
   Context ctx = env.getInitialContext();

See Also:

Serialized Form

Copyright © 2005 BEA Systems, Inc. All Rights Reserved.

Field Summary

static String

DEFAULT_INITIAL_CONTEXT_FACTORY The default (WebLogic) initial context.

Constructor Summary

Environment()
Constructs an Environment with default properties, that is, with a WebLogic initial context.

Environment(Hashtable properties)
Constructs an Environment and initializes it with the properties contained in the specified Hashtable.

Method Summary

boolean	getBoolean(String name, boolean defaultValue) Gets the value of the specified property as a boolean.
Context	getContext(String contextName) Returns a subcontext of the initial context with the specified name.
boolean	getCreateIntermediateContexts() Returns the value of the WLContext.CREATE_INTERMEDIATE_CONTEXTS property.
Hashtable	getDelegateEnvironment() Returns the value of the WLContext.DELEGATE_ENVIRONMENT property.
boolean	getEnableDefaultUser()
boolean	getEnableServerAffinity() Returns the value of the WLContext.ENABLE_SERVER_AFFINITY property.
Context	getInitialContext() Returns an initial context based on the properties in an Environment.
String	getInitialContextFactory() Returns the value of Context.INITIAL_CONTEXT_FACTORY.
boolean	getPinToPrimaryServer() Returns the value of the WLContext.PIN_TO_PRIMARY_SERVER property.
Hashtable	getProperties() Returns the properties associated with an Environment as a Hashtable.
Object	getProperty(String name) Returns the value of the specified property.
Object	getPropertyFromEnv(String name)
weblogic.protocol.ServerIdentity	getProviderIdentity() Deprecated.
String	getProviderUrl() Returns the Context.PROVIDER_URL property value.
boolean	getReplicateBindings() Returns the value of the WLContext.REPLICATE_BINDINGS property.
long	getRequestTimeout() Get the request timeout value.
Object	getSecurityCredentials() Returns the Context.SECURITY_CREDENTIAL property value.
String	getSecurityPrincipal() Returns the value of the Context.SECURITY_PRINCIPAL property.
UserInfo	getSecurityUser() Returns the UserInfo for the principal assigned to the Context.SECURITY_PRINCIPAL property.
Object	getSSLClientCertificate() Returns an RSA private key and chain of X.509 certificates set for SSL client authentication on the current thread.
Object	getSSLClientKeyPassword() Deprecated. This method will be removed in the next major release.
TrustManager	getSSLClientTrustManager() Returns the custom trust manager on the current thread used for SSL certificate chain validation.
byte[][]	getSSLRootCAFingerprints() Returns the fingerprints of the certificates of trusted authorities associated with the current thread.
String	getSSLServerName() Gets the specified expected name from the current thread of the SSL server.
String	getString(String name) Gets the value of the specified property as a String.
void	loadLocalIdentity(Certificate[] certs, PrivateKey privateKey) Loads the local identity onto the current thread given an array of certs and the private key.
void	readExternal(ObjectInput in)
Object	removeProperty(String name) Removes the specified property.
void	setBoolean(String name, boolean value) Sets the value of the specified property as a boolean.
void	setCreateIntermediateContexts(boolean flag) Set the WLContext.CREATE_INTERMEDIATE_CONTEXTS property to the String equivalent of the boolean argument flag.
void	setDelegateEnvironment(Hashtable delegateEnv) Sets the WLContext.DELEGATE_ENVIRONMENT property to the value of the argument delegateEnv.
void	setEnableDefaultUser(boolean defaultUser)
void	setEnableServerAffinity(boolean enable) Sets the WLContext.ENABLE_SERVER_AFFINITY property to the String equivalent of the boolean argument enable.
void	setInitialContextFactory(String factoryName) Sets the Context.INITIAL_CONTEXT_FACTORY property value to the value of factoryName.
void	setPinToPrimaryServer(boolean enable) Sets the WLContext.PIN_TO_PRIMARY_SERVER property to the String equivalent of the boolean argument enable.
Object	setProperty(String name, Object value) Sets the specified property.
void	setProviderIdentity(weblogic.protocol.ServerIdentity rjvm) Deprecated.
void	setProviderUrl(String url) Sets the Context.PROVIDER_URL property value to the value of the argument url.
void	setReplicateBindings(boolean enable) Sets the WLContext.REPLICATE_BINDINGS property to the String equivalent of the boolean argument enable.
void	setRequestTimeout(long timeout) Set the request timeout value in milliseconds.
void	setSecurityCredentials(Object credentials) Sets the value of the Context.SECURITY_CREDENTIAL property to the value of the argument cedentials.
void	setSecurityPrincipal(String principal) Sets the Context.SECURITY_PRINCIPAL property to the value of the argument principal.
void	setSecurityUser(UserInfo user)
void	setSSLClientCertificate(InputStream[] chain) Sets an RSA private key and chain of X.509 certificates for SSL client authentication on the current thread.
void	setSSLClientKeyPassword(String pass) Sets the password for an encrypted RSA private key on the current thread.
void	setSSLClientTrustManager(TrustManager trustManager) Customizes the trust manager on the current thread used for SSL certificate chain validation.
void	setSSLRootCAFingerprints(byte[][] fps) Establishes a set of trusted certificate authorities on the current thread.
void	setSSLRootCAFingerprints(String fps) Establishes a set of trusted certificate authorities on the current thread.
void	setSSLServerName(String name) Sets an expected name on the current thread for the SSL server.
void	writeExternal(ObjectOutput out)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_INITIAL_CONTEXT_FACTORY

public static final String DEFAULT_INITIAL_CONTEXT_FACTORY

The default (WebLogic) initial context.

See Also:

Constant Field Values

Constructor Detail

Environment

public Environment()

Constructs an Environment with default properties, that is, with a WebLogic initial context. If unset, the properties for principal and credentials default to anonymous/anonymous, and the provider URL defaults to "t3://localhost:7001".

Environment

public Environment(Hashtable properties)

Constructs an Environment and initializes it with the properties contained in the specified Hashtable.

Method Detail

getBoolean

public final boolean getBoolean(String name,
                                boolean defaultValue)
                         throws IllegalArgumentException

Gets the value of the specified property as a boolean. Returns the argument defaultValue as a default if the property is not available or invalid.

Parameters:

name - Name of property to retrieve

defaultValue - Default value for the property

Returns:

True if the property value is true

Throws:

IllegalArgumentException - if the context name is unavailable or invalid at runtime

IllegalArgumentException - if the property value is not "true" or "false"

getContext

public final Context getContext(String contextName)
                         throws NamingException

Returns a subcontext of the initial context with the specified name.

Parameters:

contextName - of the context to retrieve

Returns:

Initial context

Throws:

NamingException - if the initial context cannot be obtained

getCreateIntermediateContexts

public final boolean getCreateIntermediateContexts()
                                            throws IllegalArgumentException

Returns the value of the WLContext.CREATE_INTERMEDIATE_CONTEXTS property.

Returns:

True if intermediate contexts are in use

Throws:

IllegalArgumentException - if the property is unavailable or invalid at runtime

See Also:

WLContext.CREATE_INTERMEDIATE_CONTEXTS

getDelegateEnvironment

public final Hashtable getDelegateEnvironment()
                                       throws IllegalArgumentException

Returns the value of the WLContext.DELEGATE_ENVIRONMENT property.

Returns:

Hashtable of properties for delegate environment

Throws:

IllegalArgumentException - if the property is unavailable or invalid at runtime

See Also:

WLContext.DELEGATE_ENVIRONMENT

getEnableDefaultUser

public boolean getEnableDefaultUser()

getEnableServerAffinity

public final boolean getEnableServerAffinity()

Returns the value of the WLContext.ENABLE_SERVER_AFFINITY property.

Returns:

True if context should try to reuse existing connections & note create new ones to a cluster

Throws:

IllegalArgumentException - if the property is unavailable or invalid at runtime

See Also:

WLContext.ENABLE_SERVER_AFFINITY

getInitialContext

public final Context getInitialContext()
                                throws NamingException

Returns an initial context based on the properties in an Environment.

Returns:

Initial context

Throws:

NamingException - if the initial context cannot be obtained

getInitialContextFactory

public String getInitialContextFactory()
                                throws IllegalArgumentException

Returns the value of Context.INITIAL_CONTEXT_FACTORY. If the property has not been set and is not defined as a system property, returns the default initial context factory (weblogic.jndi.WLInitialConextFactory).

Returns:

Context factory name

Throws:

IllegalArgumentException - if the context name is unavailable or invalid at runtime

See Also:

Context.INITIAL_CONTEXT_FACTORY

getPinToPrimaryServer

public final boolean getPinToPrimaryServer()
                                    throws IllegalArgumentException

Returns the value of the WLContext.PIN_TO_PRIMARY_SERVER property.

Returns:

True if context will only connect to the primary server.

Throws:

IllegalArgumentException - if the property is unavailable or invalid at runtime

See Also:

WLContext.PIN_TO_PRIMARY_SERVER

getProperties

public Hashtable getProperties()

Returns the properties associated with an Environment as a Hashtable.

Returns:

Hashtable

getProperty

public final Object getProperty(String name)

Returns the value of the specified property. The order of lookup is to first look in environment hashtable, then in system properties, and to return null if not found.

Parameters:

name - Name of property to retrieve

Returns:

Property value as an object

getPropertyFromEnv

public final Object getPropertyFromEnv(String name)

getProviderIdentity

public final weblogic.protocol.ServerIdentity getProviderIdentity()
                                                           throws IllegalArgumentException

Deprecated.

Gets the value of the PROVIDER_RJVM property, which is the RJVM associated with an Environment.

Returns:

ServerIdentity associated with an Environment

Throws:

IllegalArgumentException - if the context name is unavailable or invalid at runtime

See Also:

WLContext.PROVIDER_RJVM

getProviderUrl

public final String getProviderUrl()

Returns the Context.PROVIDER_URL property value. Note that this property need not be set to create a WLContext from code running on the server.

Returns:

Provider URL

See Also:

Context.PROVIDER_URL

getReplicateBindings

public final boolean getReplicateBindings()
                                   throws IllegalArgumentException

Returns the value of the WLContext.REPLICATE_BINDINGS property.

Throws:

IllegalArgumentException - if the property is unavailable or invalid at runtime

See Also:

WLContext.REPLICATE_BINDINGS

getRequestTimeout

public final long getRequestTimeout()

Get the request timeout value.

Returns:

timeout value in milliseconds

See Also:

setRequestTimeout(long)

getSecurityCredentials

public final Object getSecurityCredentials()
                                    throws IllegalArgumentException

Returns the Context.SECURITY_CREDENTIAL property value.

Returns:

Password string, Certificate or UserInfo

Throws:

IllegalArgumentException - if the property is unavailable or invalid at runtime

See Also:

Context.SECURITY_PRINCIPAL

getSecurityPrincipal

public final String getSecurityPrincipal()
                                  throws IllegalArgumentException

Returns the value of the Context.SECURITY_PRINCIPAL property. If unset, defaults to guest.

Returns:

String (principal name)

Throws:

IllegalArgumentException - if the property is unavailable or invalid at runtime

See Also:

Context.SECURITY_PRINCIPAL

getSecurityUser

public final UserInfo getSecurityUser()
                               throws IllegalArgumentException

Returns the UserInfo for the principal assigned to the Context.SECURITY_PRINCIPAL property.

Returns:

UserInfo object

Throws:

IllegalArgumentException - if the property is unavailable or invalid at runtime

getSSLClientCertificate

public final Object getSSLClientCertificate()
                                     throws IOException

Returns an RSA private key and chain of X.509 certificates set for SSL client authentication on the current thread. The array of input streams are DER encoded values, the first of which is a private key, followed by X.509 certificates. All but the first of the certificates are issuer certificates for the previous certificate.

Throws:

IOException

See Also:

PEMInputStream, BufferedInputStream

getSSLClientKeyPassword

public final Object getSSLClientKeyPassword()

Deprecated. This method will be removed in the next major release.

Retrieves the password for an encyrpted private key on the current thread in an internal format.

Returns:

Password for private key

getSSLClientTrustManager

public final TrustManager getSSLClientTrustManager()

Returns the custom trust manager on the current thread used for SSL certificate chain validation.

Returns:

Custom trust manager, null if no custom trust manager has been set.

getSSLRootCAFingerprints

public final byte[][] getSSLRootCAFingerprints()

Returns the fingerprints of the certificates of trusted authorities associated with the current thread.

Returns:

Encoded byte array of authorities' certificates

getSSLServerName

public final String getSSLServerName()

Gets the specified expected name from the current thread of the SSL server. If non-null, it will be compared against the common name field in the certificate presented by the SSL server. This is typically the WebLogic Server's DNS name, e.g., www.weblogic.com.

Returns:

Domain name of an SSL server

getString

public final String getString(String name)
                       throws IllegalArgumentException

Gets the value of the specified property as a String.

Parameters:

name - Name of property to retrieve

Returns:

Value of the property as a String

Throws:

IllegalArgumentException - if the property value is not a String

loadLocalIdentity

public final void loadLocalIdentity(Certificate[] certs,
                                    PrivateKey privateKey)

Loads the local identity onto the current thread given an array of certs and the private key.

Parameters:

certs - An array of certificates

privateKey - The private key

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException

Specified by:

readExternal in interface Externalizable

Throws:

IOException

ClassNotFoundException

removeProperty

public final Object removeProperty(String name)

Removes the specified property.

Parameters:

name - Name of property to remove

Returns:

Property that was removed as an object

setBoolean

public final void setBoolean(String name,
                             boolean value)

Sets the value of the specified property as a boolean.

Parameters:

name - Name of property to set

value - Value to be set as a boolean

setCreateIntermediateContexts

public final void setCreateIntermediateContexts(boolean flag)
                                         throws IllegalArgumentException

Set the WLContext.CREATE_INTERMEDIATE_CONTEXTS property to the String equivalent of the boolean argument flag.

Throws:

IllegalArgumentException - if the property is unavailable or invalid at runtime

See Also:

WLContext.CREATE_INTERMEDIATE_CONTEXTS

setDelegateEnvironment

public final void setDelegateEnvironment(Hashtable delegateEnv)

Sets the WLContext.DELEGATE_ENVIRONMENT property to the value of the argument delegateEnv.

Parameters:

delegateEnv - Hashtable of properties

See Also:

WLContext.DELEGATE_ENVIRONMENT

setEnableDefaultUser

public void setEnableDefaultUser(boolean defaultUser)

setEnableServerAffinity

public final void setEnableServerAffinity(boolean enable)

Sets the WLContext.ENABLE_SERVER_AFFINITY property to the String equivalent of the boolean argument enable.

Parameters:

enable - True to force use of server affinity

See Also:

WLContext.ENABLE_SERVER_AFFINITY

setInitialContextFactory

public final void setInitialContextFactory(String factoryName)

Sets the Context.INITIAL_CONTEXT_FACTORY property value to the value of factoryName.

Parameters:

factoryName - Initial context factory name

See Also:

Context.INITIAL_CONTEXT_FACTORY

setPinToPrimaryServer

public final void setPinToPrimaryServer(boolean enable)

Sets the WLContext.PIN_TO_PRIMARY_SERVER property to the String equivalent of the boolean argument enable.

Parameters:

enable - True to force use of primary server

See Also:

WLContext.PIN_TO_PRIMARY_SERVER

setProperty

public final Object setProperty(String name,
                                Object value)

Sets the specified property.

Parameters:

name - Name of property to be set

value - Value (as object) to be set

setProviderIdentity

public final void setProviderIdentity(weblogic.protocol.ServerIdentity rjvm)

Deprecated.

Sets PROVIDER_RJVM property associated with an Environment.

Parameters:

rjvm - ServerIdentity

See Also:

WLContext.PROVIDER_RJVM

setProviderUrl

public final void setProviderUrl(String url)

Sets the Context.PROVIDER_URL property value to the value of the argument url.

Parameters:

url - Provider url

See Also:

Context.PROVIDER_URL

setReplicateBindings

public final void setReplicateBindings(boolean enable)

Sets the WLContext.REPLICATE_BINDINGS property to the String equivalent of the boolean argument enable.

Parameters:

enable - True to enable replicated bindings

See Also:

WLContext.REPLICATE_BINDINGS

setRequestTimeout

public final void setRequestTimeout(long timeout)

Set the request timeout value in milliseconds. JNDI requests that fail to get a response within the timeout value will fail with RequestTimeoutException. A value of 0 implies that request will never timeout.

Parameters:

timeout - value in milliseconds.

setSecurityCredentials

public final void setSecurityCredentials(Object credentials)

Sets the value of the Context.SECURITY_CREDENTIAL property to the value of the argument cedentials.

Parameters:

credentials - Certificate, password, or other credentials object

setSecurityPrincipal

public final void setSecurityPrincipal(String principal)

Sets the Context.SECURITY_PRINCIPAL property to the value of the argument principal.

Parameters:

principal - Username

See Also:

Context.SECURITY_PRINCIPAL

setSecurityUser

public final void setSecurityUser(UserInfo user)

setSSLClientCertificate

public final void setSSLClientCertificate(InputStream[] chain)

Sets an RSA private key and chain of X.509 certificates for SSL client authentication on the current thread. The array of input streams passed as an argument are DER encoded values, the first of which is a private key, followed by X.509 certificates. All but the first of the certificates are issuer certificates for the previous certificate.

The InputStreams you use must support mark and reset. If you have PEM-encoded data, you can wrap your InputStreams in PEMInputStream classes before passing them in here.

Parameters:

chain - Array of InputStreams of DER encoded values

See Also:

PEMInputStream, BufferedInputStream

setSSLClientKeyPassword

public final void setSSLClientKeyPassword(String pass)

Sets the password for an encrypted RSA private key on the current thread. If you aren't using an encrypted private key then you don't need to set this value.

Parameters:

pass - Password for private key

setSSLClientTrustManager

public final void setSSLClientTrustManager(TrustManager trustManager)

Customizes the trust manager on the current thread used for SSL certificate chain validation.

Parameters:

trustManager - Custom trust manager

setSSLRootCAFingerprints

public final void setSSLRootCAFingerprints(byte[][] fps)

Establishes a set of trusted certificate authorities on the current thread. The value specified is a set of fingerprints (MD5) of the authorities' certificates encoded as a byte[][] value.

Parameters:

fps - MD5 fingerprints of certificates

setSSLRootCAFingerprints

public final void setSSLRootCAFingerprints(String fps)

Establishes a set of trusted certificate authorities on the current thread. The value specified is a set of fingerprints (MD5) of the authority's certificates encoded as a comma-separated string of hex values.

Parameters:

fps - MD5 fingerprints of certificate(s)

setSSLServerName

public final void setSSLServerName(String name)

Sets an expected name on the current thread for the SSL server. It will be compared against the common name field in the certificate presented by the SSL server. This is typically the WebLogic Server's DNS name, e.g., www.weblogic.com.

Parameters:

name - Domain name of an SSL server

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

Specified by:

writeExternal in interface Externalizable

Throws:

IOException