BEA Systems, Inc.
WebLogic Server 5.1.0 API Reference

weblogic.jndi
Class Environment

java.lang.Object
  |
  +--weblogic.jndi.Environment
public class Environment
extends java.lang.Object
implements java.io.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();

Author:
Copyright (c) 1998 by WebLogic, Inc. All Rights Reserved., Copyright (c) 1998-1999 by BEA Systems, Inc. All Rights Reserved.
Copyright © 2000 BEA Systems, Inc. All Rights Reserved.
See Also:
Serialized Form

Field Summary
static java.lang.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(java.util.Hashtable properties)
          Constructs an Environment and initializes it with the properties contained in the specified Hashtable.
 
Method Summary
 boolean getBoolean(java.lang.String name, boolean defaultValue)
          Gets the value of the specified property as a boolean.
 javax.naming.Context getContext(java.lang.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.
 java.util.Hashtable getDelegateEnvironment()
          Returns the value of the WLContext.DELEGATE_ENVIRONMENT property.
 javax.naming.Context getInitialContext()
          Returns an initial context based on the properties in an Environment.
 java.lang.String getInitialContextFactory()
          Returns the value of Context.INITIAL_CONTEXT_FACTORY.
 boolean getPinToPrimaryServer()
          Returns the value of the WLContext.PIN_TO_PRIMARY_SERVER property.
 java.util.Hashtable getProperties()
          Returns the properties associated with an Environment as a Hashtable.
 java.lang.Object getProperty(java.lang.String name)
          Returns the value of the specified property.
 weblogic.rjvm.RJVM getProviderRJVM()
          Gets the value of the PROVIDER_RJVM property, which is the RJVM associated with an Environment.
 java.lang.String getProviderUrl()
          Returns the Context.PROVIDER_URL property value.
 boolean getReplicateBindings()
          Returns the value of the WLContext.REPLICATE_BINDINGS property.
 java.lang.Object getSecurityCredentials()
          Returns the Context.SECURITY_CREDENTIAL property value.
 java.lang.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.
 java.lang.Object getSSLClientCertificate()
          Deprecated. This method will be removed in the next major release.
 byte[][] getSSLRootCAFingerprints()
          Returns the fingerprints of the certificates of trusted authorities associated with an Environment.
 java.lang.String getSSLServerName()
          Gets the specified expected name of the SSL server.
 java.lang.String getString(java.lang.String name)
          Gets the value of the specified property as a String.
 void readExternal(java.io.ObjectInput in)
           
 java.lang.Object removeProperty(java.lang.String name)
          Removes the specified property.
 void setBoolean(java.lang.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(java.util.Hashtable delegateEnv)
          Sets the WLContext.DELEGATE_ENVIRONMENT property to the value of the argument delegateEnv.
 void setInitialContextFactory(java.lang.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.
 java.lang.Object setProperty(java.lang.String name, java.lang.Object value)
          Sets the specified property.
 void setProviderRJVM(weblogic.rjvm.RJVM rjvm)
          Sets PROVIDER_RJVM property associated with an Environment.
 void setProviderUrl(java.lang.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 setSecurityCredentials(java.lang.Object credentials)
          Sets the value of the Context.SECURITY_CREDENTIAL property to the value of the argument cedentials.
 void setSecurityPrincipal(java.lang.String principal)
          Sets the Context.SECURITY_PRINCIPAL property to the value of the argument principal.
 void setSecurityUser(UserInfo user)
           
 void setSSLClientCertificate(java.io.InputStream[] chain)
          Sets an RSA private key and chain of X.509 certificates for SSL client authentication.
 void setSSLRootCAFingerprints(byte[][] fps)
          Establishes a set of trusted certificate authorities.
 void setSSLRootCAFingerprints(java.lang.String fps)
          Establishes a set of trusted certificate authorities.
 void setSSLServerName(java.lang.String name)
          Sets an expected name for the SSL server.
 void writeExternal(java.io.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 java.lang.String DEFAULT_INITIAL_CONTEXT_FACTORY
The default (WebLogic) initial context.
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 guest/guest, and the provider URL defaults to "t3://localhost:7001".

Environment

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

Parameters:
properties - Hashtable containing initial properties
Method Detail

getProperties

public java.util.Hashtable getProperties()
Returns the properties associated with an Environment as a Hashtable.

Returns:
Hashtable

getInitialContext

public final javax.naming.Context getInitialContext()
                                             throws javax.naming.NamingException
Returns an initial context based on the properties in an Environment.

Returns:
Initial context
Throws:
javax.naming.NamingException - if the initial context cannot be obtained

getContext

public final javax.naming.Context getContext(java.lang.String contextName)
                                      throws javax.naming.NamingException
Returns a subcontext of the initial context with the specified name.

Parameters:
Name - of the context to retrieve
Returns:
Initial context
Throws:
javax.naming.NamingException - if the initial context cannot be obtained

getInitialContextFactory

public java.lang.String getInitialContextFactory()
                                          throws java.lang.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:
java.lang.IllegalArgumentException - if the context name is unavailable or invalid at runtime
See Also:
Context.INITIAL_CONTEXT_FACTORY

setInitialContextFactory

public final void setInitialContextFactory(java.lang.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

getProviderUrl

public final java.lang.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

setProviderUrl

public final void setProviderUrl(java.lang.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

getDelegateEnvironment

public final java.util.Hashtable getDelegateEnvironment()
                                                 throws java.lang.IllegalArgumentException
Returns the value of the WLContext.DELEGATE_ENVIRONMENT property.

Returns:
Hashtable of properties for delegate environment
Throws:
java.lang.IllegalArgumentException - if the property is unavailable or invalid at runtime
See Also:
WLContext.DELEGATE_ENVIRONMENT

setDelegateEnvironment

public final void setDelegateEnvironment(java.util.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

getSecurityPrincipal

public final java.lang.String getSecurityPrincipal()
                                            throws java.lang.IllegalArgumentException
Returns the value of the Context.SECURITY_PRINCIPAL property. If unset, defaults to guest.

Returns:
String (principal name)
Throws:
java.lang.IllegalArgumentException - if the property is unavailable or invalid at runtime
See Also:
Context.SECURITY_PRINCIPAL

setSecurityPrincipal

public final void setSecurityPrincipal(java.lang.String principal)
Sets the Context.SECURITY_PRINCIPAL property to the value of the argument principal.

Parameters:
principal - Username
See Also:
Context.SECURITY_PRINCIPAL

getSecurityCredentials

public final java.lang.Object getSecurityCredentials()
                                              throws java.lang.IllegalArgumentException
Returns the Context.SECURITY_CREDENTIAL property value.

Returns:
Password string, Certificate or UserInfo
Throws:
java.lang.IllegalArgumentException - if the property is unavailable or invalid at runtime
See Also:
Context.SECURITY_PRINCIPAL

setSecurityCredentials

public final void setSecurityCredentials(java.lang.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

getSecurityUser

public final UserInfo getSecurityUser()
                               throws java.lang.IllegalArgumentException
Returns the UserInfo for the principal assigned to the Context.SECURITY_PRINCIPAL property.

Returns:
UserInfo object
Throws:
java.lang.IllegalArgumentException - if the property is unavailable or invalid at runtime

setSecurityUser

public final void setSecurityUser(UserInfo user)

getCreateIntermediateContexts

public final boolean getCreateIntermediateContexts()
                                            throws java.lang.IllegalArgumentException
Returns the value of the WLContext.CREATE_INTERMEDIATE_CONTEXTS property.

Returns:
True if intermediate contexts are in use
Throws:
java.lang.IllegalArgumentException - if the property is unavailable or invalid at runtime
See Also:
WLContext.CREATE_INTERMEDIATE_CONTEXTS

setCreateIntermediateContexts

public final void setCreateIntermediateContexts(boolean flag)
                                         throws java.lang.IllegalArgumentException
Set the WLContext.CREATE_INTERMEDIATE_CONTEXTS property to the String equivalent of the boolean argument flag.

Parameters:
True - to turn on use of intermediate contexts
Throws:
java.lang.IllegalArgumentException - if the property is unavailable or invalid at runtime
See Also:
WLContext.CREATE_INTERMEDIATE_CONTEXTS

getReplicateBindings

public final boolean getReplicateBindings()
                                   throws java.lang.IllegalArgumentException
Returns the value of the WLContext.REPLICATE_BINDINGS property.

Throws:
java.lang.IllegalArgumentException - if the property is unavailable or invalid at runtime
See Also:
WLContext.REPLICATE_BINDINGS

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

getPinToPrimaryServer

public final boolean getPinToPrimaryServer()
                                    throws java.lang.IllegalArgumentException
Returns the value of the WLContext.PIN_TO_PRIMARY_SERVER property.

Returns:
True if context will only connect to the primary server.
Throws:
java.lang.IllegalArgumentException - if the property is unavailable or invalid at runtime
See Also:
WLContext.PIN_TO_PRIMARY_SERVER

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

getString

public final java.lang.String getString(java.lang.String name)
                                 throws java.lang.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:
java.lang.IllegalArgumentException - if the property value is not a String

getBoolean

public final boolean getBoolean(java.lang.String name,
                                boolean defaultValue)
                         throws java.lang.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:
java.lang.IllegalArgumentException - if the context name is unavailable or invalid at runtime
java.lang.IllegalArgumentException - if the property value is not "true" or "false"

setSSLRootCAFingerprints

public final void setSSLRootCAFingerprints(java.lang.String fps)
Establishes a set of trusted certificate authorities. 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)

setSSLRootCAFingerprints

public final void setSSLRootCAFingerprints(byte[][] fps)
Establishes a set of trusted certificate authorities. The value specified is a set of fingerprints (MD5) of the authorities' certificates encoded as a byte[][] value.

Parameters:
fps - MD5 fingerprints of certificates

getSSLRootCAFingerprints

public final byte[][] getSSLRootCAFingerprints()
Returns the fingerprints of the certificates of trusted authorities associated with an Environment.

Returns:
Encoded byte array of authorities' certificates

setSSLServerName

public final void setSSLServerName(java.lang.String name)
Sets an expected name 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

getSSLServerName

public final java.lang.String getSSLServerName()
Gets the specified expected name 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

setSSLClientCertificate

public final void setSSLClientCertificate(java.io.InputStream[] chain)
Sets an RSA private key and chain of X.509 certificates for SSL client authentication. 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.

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

getSSLClientCertificate

public final java.lang.Object getSSLClientCertificate()
                                               throws java.io.IOException
Deprecated. This method will be removed in the next major release.
Retrieves an SSL certificate chain and its private key in an internal format.

Returns:
SSL certificate chain
Throws:
java.io.IOException - if there is an IO error

setBoolean

public final void setBoolean(java.lang.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

getProperty

public final java.lang.Object getProperty(java.lang.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

setProperty

public final java.lang.Object setProperty(java.lang.String name,
                                          java.lang.Object value)
Sets the specified property.

Parameters:
name - Name of property to be set
value - Value (as object) to be set

removeProperty

public final java.lang.Object removeProperty(java.lang.String name)
Removes the specified property.

Parameters:
name - Name of property to remove
Returns:
Property that was removed as an object

getProviderRJVM

public final weblogic.rjvm.RJVM getProviderRJVM()
                                         throws java.lang.IllegalArgumentException
Gets the value of the PROVIDER_RJVM property, which is the RJVM associated with an Environment.

Returns:
RJVM associated with an Environment
Throws:
java.lang.IllegalArgumentException - if the context name is unavailable or invalid at runtime
See Also:
WLContext.PROVIDER_RJVM

setProviderRJVM

public final void setProviderRJVM(weblogic.rjvm.RJVM rjvm)
Sets PROVIDER_RJVM property associated with an Environment.

Parameters:
rjvm - RJVM
See Also:
WLContext.PROVIDER_RJVM

writeExternal

public void writeExternal(java.io.ObjectOutput out)
                   throws java.io.IOException
Specified by:
writeExternal in interface java.io.Externalizable

readExternal

public void readExternal(java.io.ObjectInput in)
                  throws java.io.IOException,
                         java.lang.ClassNotFoundException
Specified by:
readExternal in interface java.io.Externalizable

Documentation is available at
http://www.weblogic.com/docs51