Modifying objects is done by retrieving an object, modifying it, and re-submitting it to the Registry. Record modification requests require a record subclassed from ModificationBase. The ModificationBase class has a class factory method, getModificationBase, that will return an appropriate Modification base class for the desired operation:
getModificationBase(EIDRConnection, ID, CreationType)
This method returns object metadata for creationType. The schema used for the return is the same as the one used for creating an object of that type.
For example, for an object created using CreateEpisode, GetModificationBase(EIDRConn, ID, CreateBasic) returns just the fields of the basic object, and GetModificationBase(EIDRConn, ID, CreateEpisode) returns all the metadata needed to create an episode.
The underlying object must be able to support all the fields needed by creationType. It is incorrect to call GetModificationBase(DOI, CreateSeries) on the object in the previous example.
After the application modifies the metadata returned from GetModificationBase(), it submits the modifications by calling one of the methods in org.eidr.sdk.api.Modify with the modified metadata (as object or XML) and the same creationType that was passed to GetModificationBase(). Modification requests are sent to the de-duplications system and may contain one ModificationBase record (immediate or non-immediate) or multiple ModificationBase records (non-immediate only).
If you know that you want to modify a particular field and that the object you have supports it, just use the appropriate creationType. For example, if you want to change a series end date, use CREATE_SERIES as the modification base.
To add an alternate ID, which is in /FullObjectMetadata/BaseObjectdata, you should be able to call getModificationBase(EIDRConn, ID, CREATE_BASIC), extract the object from the response, add the alternate ID, and then call modifySIngleFromObj(EIDRConn, object, CREATE_BASIC).
Alas, there are some caveats in this:
- If the item you want to modify is a root object, GetModificationBase(…CREATE_BASIC) returns an object that has CreationFullInfo, which in turn can be sent to Modify(…, CREATE_BASIC) – the Registry requires FullInfo to be submitted for creationType CREATE_BASIC.
- If the item is not a root object, inherited fields are not returned and the response will contain CreationSelfDefinedInfo. This will only work when passed back to Modify(…, CREATE_BASIC) if none of the missing (inherited) fields is a required field. Otherwise, the Registry will return an error because of the “missing’”field.
- The information you get back from any other creation type can always be submitted back to modify() using the same creation type.
This all means:
- It is only safe to use GetModificationBase(…CREATE_BASIC) if you know the record is a root object or that none of the record’s required fields are inherited.
- If you want to modify a base field in a record to which that does not apply, you have to get an appropriate non-basic modification base for the object.
- You are guaranteed to be able to use CREATE_BASIC for Basic and Series objects, but for all others you have to use CREATE_TYPE, where TYPE is the underlying object’s inheritance relationship.
All of this makes it tedious to write code that handles general modifications to the base metadata of unknown records – code that wants to modify a base field has to determine whether the record is a root object or not, get the modification base that will work for it, and remember to call modify() with that creationType (which may not be CREATE_BASIC (even though the field is on the base object).
The SDK provides some methods to make this easier:
- getCreationType (Returns the CreationType.)
- getModificationObj (Returns the modification base object, which can, for example, be passed in to Modify.modifySingleFromObj.)
- getBaseObjectData returns the base object data from ModificationObj. If creationType is CREATE_BASIC, the type is CreationFullInfo; otherwise it is CreationSelfDefinedInfo.
As an example, you can get the list of alternate IDs with this (glossing over the error handling), which is the same as the other SDK calls that return Response (for example, ModificationBase).
When you call modify(), use resp.getBaseObjectData() for the object to pass in or convert to XML, and resp.getCreationType() for the creation type.
In addition, org.eidr.sdk.utils.BasInfoConverter is a utility class that converts back and forth between CreationSelfDefinedInfo and creationFullInfo.
See the source code for AltIDTool and TestBaseMetadataConverter included with the SDK for examples of how to use these classes.