IdAS Update Proposals Remove Builders

Take the approach in Option #3, but we remove the build* methods and have consumers call the add methods on the objects that envelope the object(s) to be built. i.e. an IContext builds an IDigitalSubject. An IDigitalSubject builds IAttributes and IMetadata. An IAttribute builds IPropertyValues. If this is coupled with the notion of a commit method, then maybe we can remove the ambiguity of which objects are associated with each other.

This way we can add a subject with no attributes (it hasn't been committed yet, so no worries about constraints), then we go on to add attributes, add attribute values, etc. When we've added (or modified) all data, we commit.

• Pros
  • Same as Option #3
• Cons
  • CP implementation must keep track of what's being updated until the commit method is called.

Furthermore, we can make life even simpler for consumers by making functions like this:

/**
 * Creates a new attribute (by copying a specified attribute) for this digital 
 * subject.  Optionally delays the update until IContext.commit is called.
 *
 * @param attr The attribute to be added.  The CP produces a deep copy of attr 
 * and returns it.  Subsequent updates to the attribute must be made to the 
 * returned IAttribute in order to have them affect this digital subject. 
 * @param semantics When set to "OnCommit", signifies that the addition of this attribute
 * to any backing data store is to be delayed until IContext.commit is called.
 *                  When set to "Immediate", signifies that the addition of this attribute
 * to any backing data store is to be committed before returning.  "Immediate" may not be
 * specified when the IDigitalSubject itself has not yet been committed, otherwise 
 * a <someException> is thrown.
 */
IAttribute IDigitalSubject.addAttribute(IAttribute attr, TransactionSemantics semantics)

/**
 * Creates a new attribute (of the specified type) for this digital subject.
 * The addition of this attribute to any backing data store is to be delayed 
 * until IContext.commit is called.
 * 
 * @param type The type of attribute to be created. The digital subject returns 
 * an empty IAttribute (one with a type but no values).
 */
IAttribute IDigitalSubject.addAttribute(URI type)

Similar methods would be like: (TODO: update these like above)

IDigitalSubject IContext.addSubject(IDigitalSubject subject, TransactionSemantics semantics)
ISimpleValue IProperty.addSimpleValue(ISimpleValue value, TransactionSemantics semantics)
ISimpleValue IProperty.addSimpleValue(URI type, Object data, TransactionSemantics semantics)
IComplexValue IProperty.addComplexValue(IComplexValue value, TransactionSemantics semantics)
IProperty IComplexValue.addProperty(IProperty property, TransactionSemantics semantics)
etc.

Note that this allows a caller to:

• Immediately add a pre-existing attribute to a subject.
• Add a pre-existing attribute and commit the add at a later point (possibly along with other modifications)
• Produce a (non-commited) attribute to which value(s) may be added and commit the add at a later point (possibly along with other modifications)

IContext.commit semantics

• This should probably also allow a flag to signify whether all modifications are atomic or not (all succeed or all fail).
• If we do this, we should make a way for commit to return some indication of which operation(s) caused a failure.
• Also, commit could allow another flag that indicates that while the operations are not being committed atomically, either each should be tried, or that the operation returns on the first failure.

So, something like this maybe:

/**
 * Commits all previously executed update operations which had 
 * semantics set to "OnCommit" to the backing data store.
 * @param semantics When set to "Atomic", all updates are performed 
 * in sequence, but as an atomic operation. 
 * This means that all updates will either succeed or fail.  
 * If the context provider cannot ensure this level
 * of service, a <someException> is thrown.
 *                  When set to "ContinueOnFail", all updates are
 * performed in sequence, but not as an atomic operation. If any 
 * update fails, execution continues to attempt the remaining updates.
 * Upon completing all attempted updates, if any had failed a 
 * <someException> is thrown which may be used to convey information
 * about the update(s) that failed.
 *                  When set to "ThrowOnFail", all updates are
 * performed in sequence, but not as an atomic operation. If any 
 * update fails, a <someException> is thrown.
 */
IContext.commit(TransactionSemantics semantics)

Deletes

Now, how are things deleted? We could:

• Put a delete on each interface (IDigitalSubject.delete(TransactionSemantics semantics), IAttribute.delete(TransactionSemantics semantics), IMetadata.delete(TransactionSemantics semantics), IPropertyValue.delete(TransactionSemantics semantics)). This would delete the object upon which the method is being called.
• Put a delete<ContainedThing> method at each container like IContext.deleteSubject(String subjectID, TransactionSemantics semantics), IDigitalSubject.deleteAttribute(URI attrName, TransactionSemantics semantics), IAttribute.deleteValue(URI type, Object value, TransactionSemantics semantics), etc.
• Both of the above.
  • I (Jim) prefer both at first glance.
    • On second thought, two ways of doing the same thing is confusing.
    • If I were to chose one, I'd probably pick the first since users will probably be at the element they want to delete at the point that they want to delete it. Also it doesn't require them to name the thing being deleted.
    • On the other hand, placing methods on the container of a thing lets us do things like IAttribute.deleteValue(type, data) or IAttribute.deleteValues() so one could delete all values of an attribute without deleting the attribute itself