/**

     * Update the state of an external object in its repository. If the update

     * succeeds, return the saved state. If it fails because the external

     * object was independently modified, then return the current state of the

     * object.

     * <p>

     * Only modified properties are included in the <code>newState</code>

     * map. Since repositories may alter the values of properties when they are

     * saved, the actual, post-save values of the properties should be returned

     * in the <code>returnedState</code> map. The Interop service will then

     * schedule incoming synchronization with that state. All properties that

     * have changed as a result of the save should be returned.

     * <p>

     * It's possible that the properties in <code>newState</code> are based on

     * an older copy of the external properties than what actually exists in the

     * repository (known as a "stale data" condition). In that case, if the

     * repository can detect such a situation and prevent the overwrite, this

     * method should return false. It is the external repository's responsibility

     * to send in the latest state at some point. Until then, the sync status

     * of the proxy will be PENDING.

     * <p>

     * If the object cannot be updated for some reason other than "stale data",

     * then this method should throw some kind of runtime exception. Any message

     * text in the exception will be stored in the proxy.

     * 

     * @since 0.6

     * 

     * @param typeName

     *      the type name of the external object, if specified by the

     *      synchronization rule being used, or <code>null</code> if no type

     *      name specified. (The type name may be inferable, or there may be

     *      only one type supported by a manager, so this argument is optional.)

     * @param uri

     *      the URI of the external object

     * @param newState

     *      the properties to modify for the object

     * @param lastState

     *      the most recently received state for the external object, if any,

     *      or <code>null</code> if there isn't any

     * @param returnedState

     *      the current state of the object, either after it has been saved,

     *      or if the save failed because the object was independently

     *      modified

     * @param propertyNames

     *      the names of properties that should be returned in the returnedState

     *      argument

     * @param externalConnection

     *      the external connection being used by the synchronization rule,

     *      if any; provided for contacting the external repository or for

     *      obtaining any properties of the connection specific to this manager;

     *      may be <code>null</code>

     * @param processArea

     *      any process area associated either with the connected Jazz item,

     *      if known, or the synchronization rule being used.

     *      Provided for the external manager to use as an indication of the

     *      "source" of an item, in case it supports multiple Jazz connections

     *      to a single external object and needs to distinguish them somehow.

     * @return

     *      <code>true</code> if the external object was successfully updated;

     *      <code>false</code> if the update failed due to a "stale data"

     *      condition

     * @throws RuntimeException for an error other than "stale data"

     */

actually, after all this time, I have to report I was wrong..

when updateState() is called, there are 4 important parameters

Map newState
Map lastState
Map returnedState
List propertyNames

I've just found a longstanding issue with my code..

newState is NOT a state...!!. it is a set of CHANGED properties, and ONLY the changes.

propertyNames contains the list of ALL the properties for this item (depends on what this manager is processing for), and only applies to the lastState map.

So, the mechanism is

create a new state in returnedState, that combines lastState
and the changed properties.

I do this by

1. copying the lastState map properties to returnedState map
oh if java had good assignment operator support
2. process the properties in newState, and apply them to returnedState map.

I think the abstract class definition for the parameters to updateState() should be changed to reflect the facts..

newState -> changedProperties
propertyNames -> propertyNamesAll

sam

nice. where do you find that? I have never seen that anywhere
not in the source of the base class, I don't see a doc folder...

if for some reason I cannot connect or complete the syncronization with my repository, and return false from the updateState() method.. will this be retried at a later time?