Proposed Changes to Attribute Copy and Item Assignment Methods

Simulation Modeling Toolkit (SMTK) Design
1

I’m working on extending the copyAttribute method in attribute::Resource to allow the following:

  • Setting the new attribute’s UUID to be the same as the original attribute (assuming it is being copied into a different resource).
  • Allowing the copy method to permit items to be not available in the copy of the attribute
  • Indicating that the attribute’s Definition should not be copied if it does not exist in the target attribute resource.
  • Removing the assumption that the items in the copy are in the same sequence as in the original.

The above are needed when trying to migrate an existing attribute resource to an updated version of the underlying template.

In addition, I propose adding the following new options to the Item Assignment Options:

  • IGNORE_MISSING_CHIDLREN - children items can be missing in the target Item. This can happen if the copy’s Item Definition is of a different version from the original
  • DO_NOT_VALIDATE_REFERENCE_INFO - directly copy reference, component, and resource item values without validating them
  • ALLLOW_PARTIAL_Values - indicates that if the target Item has different number of value or constraints that it is ok for only some of the source values to be copied. If not set then if all of the values can not be copied the assignment will fail.
  • DISABLE_COPY_ATTRIBUES

In order to support these new features I plan on deprecating the existing attribute::Resource::copyAttribute(AttributePtr att, bool copyAssociations, unsigned int itemOptions) and replace it with:

attribute::Resource::copyAttribute(const AttributePtr& att, unsigned int attributeCopyOptions = 0, unsigned int itemAssignmentOptions = 0, smtp::io::Logger& logger = smtp::io::Logger::instance())

I also plan on removing the CopyOptions for the attribute resource since these are not being used and to instead add CopyOptions to Attribute.h that contains the following:

  • COPY_ASSOCIATIONS - Indicates that association information should be copied and re-validated. The copy will fail if all of the following are true:
    • The source attribute has associations
    • The resource creating the copy is the same as that source attribute
    • The source attribute’s definition is marked unique
  • ALLOW_PARTIAL_ASSOCIATION - allows partial copying of associations. If this is not set and not all of the associations can be copied, the copy method will fail.
  • DO_NOT_VALIDATE_ASSOCIATIONS - Indicates that association information should be copied and not re-validated.
  • COPY_UUID - Indicates the new attribute have the same UUID value as the original. Note that should only be used when original attribute is in a different resource
  • IGNORE_MISSING_ITEMS -Items can be missing in the copy. This can happen if the copy’s Definition is of a different version from the original
  • DO_NOT_COPY_MISSING_DEFINITION - If not set and if the attribute’s definition is not found in the resource that will contain the attribute copy, the definition will also be copied into the resource. The copy will fail if set and if the resource does not have the source attribute definition.\

In terms of behavior changes

The current copyAttribute method, when told to copy association information, will choose to ignore it if the attribute’s Definition is unique and if the attribute copy is in the same resource as the original. The reason behind this is the fact that under these circumstances the association information can not be copied. I proposed that instead of ignoring the request, that the copy should instead fail.

Updated API Changes

I ended up creating a new class CopyAssignmentOptions that is used to control both attribute copying and Item assignment mechanisms. The class’s information managed by three other class:

  • AttributeCopyOptions - which controls how new attributes can be created/copied and provide the following options:
    • CopyUUID - if true the new attribute will have the same UUID as the source attribute
    • CopyDefinition - if true, indicates that if source attribute’s Definition does not exist in the Resource managing the proposed copy, copying the Definition is permitted
  • AttributeAssignmentOptions - controls the assignment process is between 2 attributes and provides the following options:
    • IgnoreMissingItems - if set, indicates items in the source attribute do not have to exist in the copy
    • CopyAssociations - if set, indicates that the source’s association information should also be copied
    • AllowPartialAssociations - if set, indicates that it is ok that not all of the source’s associations can be copied. This could be due to the attribute Definitions having different requirements (including different limits on the NumberOfValues)
    • DoNotValidateAssociations - a hint indicating that all of the source attribute’s associations can be blindly copied
  • ItemAssignmentOptions - controls the assignment process is between 2 items and provides the following options:
    • IgnoreMissingChildren - if set, indicates children items in the source item’s do not have to exist in the copy
    • AllowPartialValues - if set, indicates that it is ok that not all of the source item’s values can be copied. This could be due to the item Definitions having different requirements (including different limits on the NumberOfValues/NumberOfGroups)
    • IgnoreExpressions - if set, ValueItem’s expressions will not be copied
    • IgnoreReferenceValues - if set, ReferenceItem’s values will not be copied
    • DoNotValidateReferenceInfo - a hint indicating that all of a ReferenceItem values can be blindly copied
    • DisableCopyAttribute - if set and if the process of copying an item would cause an attribute to be created, do not create the attribute and return failure. If an attribute is copied, the AttributeCopyOptions and AttributeAssignmentOptions will be used.
2

@dcthomp @rohith @Aaron @waj334 @mledesma - FYI - Comments are welcome!

4

  1. Suggest changing SET_ATTRIBUTE_UUID to just COPY_UUID.

  2. For the association-copy options, I think we should indicate the precedence between the 3 option flags. If all 3 bits are set, for example, I suppose the FORCE_COPY_ASSOCIATIONS option should be applied and the other 2 options ignored.

  3. For the COPY_ASSOCIATIONS, is that the original text in the code? That was written presuming that the original and copy attributes have the same association rules. For the more general case, I presume the intent is to validate the associations when they are applied to the copied attribute, and fail if the associations fail for any reason unless the ALLOW_PARTIAL_ flag is set. So I think we should either drop the “copy will fail if all of the following are true” stuff or update the text to say something like “for example” or “note that”.

  4. Related to all of this is whether or not the copyAttribute code can trigger an automatic resource load. My guess is that the current logic for validating associations (or any reference item) works that way, but I haven’t snooped around that part of smtk in a long time.

5

You mean if it does exist (at least some other Definition of the same name)? Without its definition, what good is an attribute?

Edit: nevermind, I see you used a double negative.

6

Instead of using an unsigned int for the various options in the replacement, I recommend passing a pointer to an in-class struct holding (currently) an unsigned int. This will give future options the ability to add more data without breaking the API.

7

Maybe FAIL_ON_MISSING_DEFINITION would be more descriptive?

8

If this is option is set and the Definition does not exist in the target Resource then the copy method will fail.

9

Not really - since the default behavior is to copy the Definition if it does not exist in the target Resource.