Chronological Thread 

< Chronological >      < Thread >

---

--- CellML-APISPEC.idl 2005-10-25 14:12:44.000000000 +1300
+++ /people/amil082/code/CellML_DOM_API/interfaces/CellML-APISPEC.idl
2006-02-16
12:00:32.442500663 +1300
@@ -161,8 +161,8 @@

/**
* The collection of extension elements associated with this CellML
- * element. The list is not "live", and so it will not automatically
update
- * as changes to the model are made.
+ * element. The list is "live", and so it will automatically update
+ * as changes to the underlying DOM representation are made.
*/
readonly attribute ExtensionElementList extensionElements;

This documentation change makes the CellML API more consistent, and makes more
sense.

@@ -270,7 +270,9 @@
* never read from an XML file or written out, but are for the
application
* to use for any purpose it likes.
* Implementations in languages in which the ability to do this on any
- * object is built in may choose not to implement this.
+ * object is built in may choose not to implement this, provided that the
+ * implementation does not offer the possibility of remote access to the
+ * object.
* If the key already exists, then the existing user-data should be
removed
* and the new user-data added.
* @param key A string to identify the annotation.

This change means that compliant implementations can only choose not to
provide
the user data setting function if they are local only.

@@ -311,7 +313,9 @@
*/

/**
- * This allows a model with a different cellmlVersion to be returned.
+ * This allows a model with a different cellmlVersion to be returned.
This
+ * function will automatically flatten CellML 1.1 models if they contain
+ * imports, and conversion to CellML 1.0 is requested.
* @param cellmlVersion The new version of CellML. The string should be
1.0
* or 1.1
* @raises CellMLException if the version is not supported by the API.

This change clarifies that the function must flatten the model when changing
from 1.1 to 1.0, rather than just change the namespaces.

@@ -348,7 +352,15 @@
readonly attribute UnitsSet localUnits;

/**
- * The collection of units, including those from imports.
+ * The collection of units. Provided that the imports are instantiated,
+ * this will fetch units in both direct and indirect imports. If the
+ * import containing the unit definition has been instantiated, iterating
+ * the set will return the unit definition, otherwise it will return
+ * the ImportUnit. If an import containing unit definitions is
instantiated
+ * after iterator creation but before unit retrieval, the implementation
+ * may choose to return either the ImportUnit or the unit definition.
+ * Applications must not rely upon the behaviour of any particular
+ * implementation in this case.
*/
readonly attribute UnitsSet childUnits;

This change clarifies the semantics of childUnits with respect to models that
import other models. It also clarifies that applications should not rely upon
iterators to immediately start returning elements from newly instantiated.

@@ -358,16 +370,22 @@
readonly attribute CellMLComponentSet localComponents;

/**
- * returns all components with interface 'CellMLComponent' in the model.
- * This includes components which may or may not have been instantiated.
+ * Returns all components with interface 'CellMLComponent' in the model.
+ * Provided that the imports are instantiated, this will fetch components
+ * in both direct and indirect imports. If the import containing the
+ * component definition has been instantiated, iterating the set will
+ * return the component definition, otherwise it will return the
+ * ImportComponent. If an import containing component definitions is
+ * instantiated after iterator creation but before component retrieval,
+ * the implementation may choose to return either the ImportComponent or
+ * the component definition. Applications must not rely upon the
behaviour
+ * of any particular implementation in this case.
*/
readonly attribute CellMLComponentSet components;

This change clarifies the semantics of components with respect to models that
import other models. It also clarifies that applications should not rely upon
iterators to immediately start returning elements from newly instantiated.

/**
* Model connections. If any imports have been fully instantiated, then
it
* includes connections relevant to those also.
- * Adding or removing from this collection must always add the connection
- * to the correct model.
*/
readonly attribute ConnectionSet connections;

This change removes a comment which is out of date because it sets do not
allow
the model to be changed.

@@ -381,7 +399,8 @@
);

/**
- * This fully instantiates the import definitions
+ * This fully instantiates the import definitions. It will then
recursively
+ * instantiate all imports in the imported models.
*/
void fullyInstantiateImports();

This clarifies that fullyInstantiateImports recursively instatiates imports in
imported models.

@@ -572,7 +591,8 @@
/**
* Gets the 'import number' in which this component is contained.
* 0 means it is in the parent, and all other numbers are those allocated
- * for each import.
+ * for each import. This must match the uniqueIdentifier on the import
+ * element which causes the importation of this model.
*/
readonly attribute unsigned long importNumber;
};

This clarifies that importNumber should match the Import::uniqueIdentifier

@@ -581,7 +601,7 @@
: NamedCellMLElement
{
/**
- * True if this set of units is base units, or false otherwise.
+ * True if this units element defines a base unit, or false otherwise.
*/
attribute boolean isBaseUnits;

This rewords the to comment to be less confusing.

@@ -632,7 +652,14 @@
: CellMLElement
{
/**
- * The URI in the xlink:href attribute.
+ * The URI in the xlink:href attribute. Changing the URL in the xlinkHref
+ * on an instantiated import will cause the import to become
+ * uninstantiated. If there are any iterators(of a kind which is required
+ * to return elements from more than one model) which were created from
the
+ * sets prior to changing xlinkHref, an implementation may choose to
+ * continue to provide elements from the previously instantiated import.
+ * Applications must not rely upon the behaviour of any particular
+ * implementation in this case.
*/
readonly attribute URI xlinkHref;

This clarifies the effect of modifying the href attribute, and makes it clear
that applications should not rely on the behaviour of import spanning
iterators
after doing this.

@@ -655,14 +682,16 @@
readonly attribute ConnectionSet importedConnections;

/**
- * Fully instantiate the import.
- * @todo Definition of full instantiation.
+ * Causes the model referenced by the href attribute to be loaded using
the
+ * same model loader used to load this model.
*/
void fullyInstantiate();

Give a definition of what fullyInstantiate does.

/**
* Returns true if fullyInstantiate has previously been called on this
- * import, or false otherwise.
+ * import, or false otherwise. Note that a call to
fullyInstantiateImports()
+ * on a model which is an ancestor of this one in the import tree shall
be
+ * treated as if it were a call to fullyInstantiate() on all imports.
*/
readonly attribute boolean wasFullyInstantiated;

Fixes a possible point of confusion with respect to fullyInstantiateImports().

@@ -681,13 +710,13 @@
{
/**
* The name of the component referenced by this import component.
- * @todo what happens if this is changed after fullyInstantiate()?
*/
attribute CellMLAttributeString componentRef;

Remove a comment which doesn't really need to be there.

/**
* Fully instantiate the import.
- * @todo Definition of full instantiation.
+ * @query Do we need this? It seems like it is an alias for
+ * parentElement()->fullyInstantiate(), which seems rather
pointless.
*/
void fullyInstantiate();

I am proposing that fullyInstantiate() be removed from this particular
interface.

@@ -712,7 +741,8 @@

/**
* Fully instantiate the import.
- * @todo Definition of full instantiation.
+ * @query Do we need this? It seems like it is an alias for
+ * parentElement()->fullyInstantiate(), which seems rather
pointless.
*/
void fullyInstantiate();

I am proposing that fullyInstantiate() be removed from this particular
interface.

@@ -786,7 +816,7 @@
/**
* The name of the component containing this CellMLVariable.
*/
-
+ readonly attribute CellMLAttributeString componentName;
};

/**

As discussed earlier.
@@ -851,12 +881,12 @@
/**
* The collection of relationship references.
*/
- attribute RelationshipRefSet relationshipRefs;
+ readonly attribute RelationshipRefSet relationshipRefs;

As discussed earlier.

/**
* The collection of component references.
*/
- attribute ComponentRefSet componentRefs;
+ readonly attribute ComponentRefSet componentRefs;

As discussed earlier.

/**
* @todo Find out what Matt meant by the following
@@ -903,22 +933,28 @@
: CellMLElement
{
/**
- * The name of the first component. This component
+ * The name of the first component. The returned name shall be the same
+ * name as found in the component_1 attribute(that is, the implementation
+ * shall not translate the name of imported components).
*/
attribute CellMLAttributeString firstComponentName;

Make it clear as to what name this should return when imports make it
ambiguous.

/**
- * The name of the second component.
+ * The name of the second component. The returned name shall be the same
+ * name as found in the component_2 attribute(that is, the implementation
+ * shall not translate the name of imported components).
*/
attribute CellMLAttributeString secondComponentName;

Make it clear as to what name this should return when imports make it
ambiguous.

/**
- * The first component.
+ * The first component. This component shall be the component definition
if
+ * imports have been instantiated, and otherwise shall be the
ImportComponent.
*/
attribute CellMLComponent firstComponent;

Clarify what should be returned.

/**
- * The second component.
+ * The second component. This component shall be the component definition
if
+ * imports have been instantiated, and otherwise shall be the
ImportComponent.
*/
readonly attribute CellMLComponent secondComponent;
};

Clarify what should be returned.

@@ -931,7 +967,7 @@
{
/**
* The name of the first variable. The variable name is interpreted only
in
- * the context of MapComponents, and so may only be read or set once the
+ * the context of MapComponents, and so may only be read or set after the
* MapVariables is added to a Connection, and the Connection has in turn
* been added to a model. It also requires that the component name has
* already been set.

once => after is easier to read.
@@ -943,7 +979,7 @@

/**
* The name of the second variable. The variable name is interpreted only
in
- * the context of MapComponents, and so may only be read or set once the
+ * the context of MapComponents, and so may only be read or set after the
* MapVariables is added to a Connection, and the Connection has in turn
* been added to a model. It also requires that the component name has
* already been set.

once => after is easier to read.
@@ -1457,7 +1493,7 @@
* Returns a CellMLElementIterator that can be used to iterate through
the
* elements. The iteration order is undefined.
*/
- UnitIterator iterateImports();
+ UnitIterator iterateUnits();
};

interface ConnectionIterator : CellMLElementIterator

As discussed before.

There are also two other issues which are still open:
1) Asynchronous loading of models. The current API specification presumes
synchronous(i.e. blocking) model loading, which will be inappropriate in some
cases.
2) Threadsafety. This is a difficult issue in implementations built on top of
the DOM, because the DOM API provides no way to atomically perform several DOM
operations. However, we could tell our users not to change the model an the
underlying DOM at the same time, and still protect the CellML API itself(i.e.
two concurrent calls to functions in the cellml_api namespace are okay, as are
two concurrent calls to functions in the dom namespace, but concurrent calls
to
functions in the dom namespace and the cellml_api namespace are not allowed.

Opinions?

Best regards,
Andrew


----------------------------------------------------------------
This message was sent using IMP, the Internet Messaging Program.

---

• [cellml-discussion] Documentation updates for the CellML API, Andrew Miller, 02/16/2006

---

Archive powered by MHonArc 2.6.18.