[sca-j] ISSUE 4 - Proposed spec text for dependency reinjection

[Simon Nash <NASH@uk.ibm.com>]

Here's my attempt to merge the contents of the v5 spreadsheet with 
Michael's original text.  There's bit more work still to do to capture the 
decisions we made regarding callback injection and reinjection.

- - - - begin spec words - - - -

References MAY be reinjected after the initial creation of a component if 
the reference target changes due to a change in wiring that has occurred 
since the component was initialized.  In order for reinjection to occur, 
the following MUST be true:
1) The component MUST NOT be STATELESS or REQUEST scoped.
2) The reference MUST use either field-based injection or setter 
injection. References that are injected through constructor injection MUST 
NOT be changed.  Setter injection allows for code in the setter method to 
perform processing in reaction to a change.
3) If the reference has a conversational interface, then reinjection MUST 
NOT occur while the conversation is active.
 
If a reference target changes and the reference is not reinjected, it MUST 
continue to work as if the reference target was not changed.
 
If an operation is called on a reference where the target of that 
reference has been undeployed or has become unavailable, the SCA runtime 
SHOULD throw InvalidServiceException.  It the target of the reference is 
changed, the reference MAY continue to work, depending on the runtime and 
the type of change that was made.  If it doesn't work, the exception 
thrown will depend on the runtime and the cause of the failure.

A ServiceReference that has been obtained from a reference by 
ComponentContext.cast() corresponds to the reference that is passed as a 
parameter to cast().  If the reference is subsequently reinjected, the 
ServiceReference MUST continue to work as if the reference target was not 
changed.  If the target of a ServiceReference has been undeployed or has 
become unavailable, the SCA runtime SHOULD throw InvalidServiceException. 
If the target of a ServiceReference is changed, the reference MAY continue 
to work, depending on the runtime and the type of change that was made. If 
it doesn't work, the exception thrown will depend on the runtime and the 
cause of the failure.
 
A reference or ServiceReference accessed through the component context by 
calling getService() or getServiceReference() MUST correspond to the 
current configuration of the domain.  If the target has been undeployed or 
has become unavailable, the result SHOULD be a reference to the undeployed 
or unavailable service, and attempts to call business methods SHOULD throw 
InvalidServiceException.  If the target has changed, the result SHOULD be 
a reference to the changed service.
 
The rules for reference reinjection also apply to references with a 
multiplicity of 0..N or 1..N.  This means that in the cases listed above 
where reference reinjection is not allowed, the array or Collection for 
the reference MUST NOT change their contents.  In cases where the contents 
of a reference collection MAY change, then for references that use setter 
injection, the setter method MUST be called for any change to the 
contents.  The injected collection MAY be the same collection object as is 
currently used by the component, but with some change to its contents.

- - - - end spec words - - - -

    Simon

Simon C. Nash, IBM Distinguished Engineer
Member of the IBM Academy of Technology
Tel. +44-1962-815156  Fax +44-1962-818999





Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 
741598. 
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU