| The Ground Rules

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