CellML API development

This page is for notes relevant to the development of the new CellML API(based on the IDL).

At the moment, there are some issues which need to be studied further:

1. How we will provide the user with access to RDF.

   (matt) Since there isn't a well defined API for RDF, I think the best we can do is provide the RDF as an overall RDF/XML Document

   (Andrew) This probably needs to be discussed further with more people. RDF/XML is far from being canonical, and it is quite heavyweight. If we are implementing it on top of the DOM, it does make thing easier, but at the same time, it is a decision which could be difficult to change later.

   (Meeting: 25 Oct 2005) We will add a getRepresentation method that takes a string, and returns an object that can be cast to a specific type(depending on the string passed in). Strings are to be URNs. There are two mandatory types, "http://www.cellml.org/RDFXML/string" and "http://www.cellml.org/RDFXML/DOM", which provide string serialisations and DOM RDF/XML views. Implementors are free to implement their own additional represetnations at URNs under their jurisdiction.

2. Whether cellmlVersion in cellml_api::CellMLElement should be marked readonly. The case for this is that changing the version requires changing the namespace of a node, which is something that you can't do with the DOM.

   (matt) We need to be able to modify the version. It is a rather infrequent and particular thing to do and would require some validation.

   (Andrew) So we need to define how it would interact with the DOM(in the DOM centric API). We could perform a manual clone of the entire tree, copying everything but changing the namespace. The problem is that anyone who holds onto a DOM node from before this now has a node that isn't even in the model anymore.

   (Meeting: 25 Oct 2005) It was agreed that the attribute should be marked readonly, but there should be a new method which creates a completely separate model with a specified version. This should do more than simply changing the version, as it also needs to produce valid 1.0 models from CellmL 1.1 models. It was agreed that the model needs to be "completely instantiated" otherwise implementations should fail with an error.

3. Better definitions of what validate() on cellml_api::CellMLElement is actually supposed to do, and how it reports errors.

   (matt) Bill and I have been going through this w.r.t an upgrade of the Java CellML editor. I'll compile a list of specific validate algorithms for each kind of element. I guess we need to sort out exceptions vs return values and what makes sense. The same attention needs to be given to modification of CellML structures, e.g. removing a connection or component: there are a set of operations which would be considered atomic and if completed successfully would maintain a consitent model that doesn't need complete validation. It also requires a commit and rollback.

4. Consideration of whether base_uri in cellml_api::Model and xlink_href in CellMLImport should be read only. The case for this is that there is no way to create a base_uri anyway, and cellml_api::URIs are mutable, so why not use the getter, and then change the existing cellml_api::URI.

   (matt) Why wouldn't you want people to be able to change the import URI (i.e. the xlink_href)? As for the model base URI, it doesn't need to be mutable that I can see.

   (Andrew) You can change the value of the actual URL. The problem is that you shouldn't be able to assign the cellml_api::URI object itself, and instead modify the existing object.

   (Meeting: 25 Oct 2005) It was agreed that we should flag these attributes readonly.

5. How do imports get loaded? We are not, at present, providing any context back to the application to request that a model gets loaded.

   (matt) I thought I answered this in my `api document <http://www.cellml.org/wiki/apifiles/APIideas.pdf>`_. See the section General Notes.

   (Andrew)I can't find anything about that, so perhaps I phrased my question poorly. I meant that we can't expect the API to handle HTTP/file access, or any other protocol that the user might specify, to load imports, so instead we should have an interface which the application implements, where the API can tell the application that it needs a file loaded, and have the application call it back when the load is complete.

   (Meeting: 25 Oct 2005) This was discussed, and there was agreement that we need some sort of context, and that it should support non-blocking and blocking workflows. Andrew to produce a specification based on the previous one.

6. No definition of "full instantiation" has been provided, so exactly what this does needs to be clarified.

   (matt) See above (number 5).

7. Define what happens if cellml_api::ImportComponent::componentRef or ImportUnits::unitsRef is changed after instantiation.

   (matt) If the model imports have been instantiated, then instantiate the new reference, otherwise leave as simply references.

8. What do get_parent_component_names and get_children_component_names do in cellml_api::Group?

   (matt) For a given component_ref in a group get_parent_component_names will return the parent component name that the parent component_ref refers to in the group tree, and get_children_component_names should return a list of component names that the child component_refs refer to in the group tree. The get_parent_component_names should really be singular : get_parent_component_name. Also, if this is going to provide use, then we should add a get_sibling_component_names. These methods help other methods that validate interfaces for encapsulated groups and would likely help people creating user defined groups where the tree structure has alternative meaning.

9. How the user can create various kinds of cellml_api::CellMLElement (there are no constructor methods on cellml_api::Model).

   (matt) Page 17 of my API doc talks about Factories. This is the closest I came to a signature that a constructor might have if one desides to put custom construction inside such. Otherwise it's simply up to the factory to construct bare instances and set attributes. So yes, this is unresolved so far in the documentation.

   (Andrew) I will add factories to IDL soon. However, I suspect that we only need one factory interface, and then we can make that available from CellMLDocument. It might also make sense to tie the objects to a particular CellMLDocument anyway(the DOM does this).

   (Meeting: 25 Oct 2005) It was agreed that the constructors should be moved to CellMLDocument, as long as there is a clone function(so that "default attribute" functionality can be provided).

10. Some better way to identify variables. Ideally, it should be possible to get a unique name of the form importidentifier::component::variable, where importidentifier is a number or code assigned to each import at load time.

    (matt) Is this in light of an implicit naming mechanism for imported components and variables? Do imports require a user defined identifier? I guess one of the most tricky cases is where there are multiple imports of the same component from the same model into the current model.

    (Andrew) I think that, as it is only part of the API, we don't really need to let the user choose a name. Perhaps simply numbering them is enough(mozCellML does this, and it works quite well).

    (Meeting: 25 Oct 2005) This shouldn't be in strings, so instead we pass the objects around everywhere.

11. Some way to "adopt" nodes from one model to another, i.e. to allow a node taken from one model to be used in another model.

    (matt) What does node mean?

    (Andrew) I meant node in the XML sense(a node is the superclass of element, and many other types). What I meant is that we need something similar to document.adoptNode() from DOM, which allows a CellMLElement from one Model to be used in another different Model.

    (Meeting: 25 Oct 2005) Agreed that this should be there.

12. A better definition of when structures such as lists are "live", i.e. they change with the rest of the model, and when they are fixed at the time of a call.

    (matt) I imagine most are live, especially if chaning an import reference of an instatiated model could change the contents of most lists. We would need to go through each one I presume. My inclination is that all should be thread safe.

    (Andrew) Liveness and threadsafety are, to a certain degree, mutually exclusive(unless you gain a separate mutex before touching anything). The reason is that you will commonly get a list, obtain the length, and then loop through everything on the list. If the list length can change on you, then problems arise. Therefore, perhaps the list should be fixed when it is created. This is what DOM does(although DOM lists are immutable, and changes are made on the nodes instead of on the lists).

    (Meeting: 25 Oct 2005) After much discussion, it was agreed that all collections should be immutable, and all functions on collections should be moved to the CellMLElements. Collections themselves should not be live, and so changes to the CellMLElement should not take effect on existing lists. CellMLElements which are still on the list but have been deleted should have a null parent. Unlike the lists themselves, CellMLElements are "live".