Parameters and Return Values

When writing a service provider, you must keep in mind certain rules on how to treat incoming parameters and outgoing return values. Not only do these rules affect the correctness of the service provider and ultimately the correctness of the program that uses it, but they also have security implications. These rules apply to method invocations on the Context interface and its subinterfaces and are discussed in the next subsections.
Parameters Are Owned by the Caller
When a service provider accepts a parameter from a caller as part of a context method invocation, it must not modify the parameter's contents. Suppose that a service provider receives a java.util.Hashtable as an environment parameter. Then it must not add, delete, or change any item in the Hashtable. If the provider must use a modified version of the Hashtable (for example, by deleting any security-related properties), then it must do so only after cloning the Hashtable.
In another example, when the provider gets a Name parameter, it must not add, delete, or change any component in the name.
Parameters Are Valid Only During Invocation
A service provider must not maintain any pointers to (mutable) parameters beyond the method invocation. If a service provider must retain information passed in the parameters, then it should clone or copy the information to locally accessible variables.
For example, if a caller invokes LdapContext.setRequestControls() with a non-null Control[], then the service provider should copy the array before returning from the call. After the call, any changes that the caller makes to its array should not affect the service provider, and vice versa.
Return Values Are Owned by the Caller
When a service provider returns a (mutable) object to the caller, it should give up ownership of the object. The caller then is free to make changes to the returned object, and such changes should have no effect on the service provider.
For example, if two callers invoke LdapContext.getRequestControls(), then the Control[] that each receives is its own copy. Each caller can manipulate that result without affecting the other caller. Similarly, if two callers invoke Context.getEnvironment(), then the java.util.Hashtable that each receives can be manipulated independently without the other caller's being affected.
To support this behavior, the service provider typically needs to clone a mutable result (that can be returned to multiple callers) before returning it.

The Ground Rules