Issue 4124: particular valuetype inheritance is truncatable. Jira Issue BQS-2
Issue 4125: UML model on p.18 does not specify multiplicities on both ends of associati Jira Issue BQS-3
Issue 4126: specifications of multiplicity and other semantics in UML diagram normative Jira Issue BQS-4
Issue 4127: Include an XMI document representing the UML model Jira Issue BQS-5
Issue 4520: query-able and non query-able attributes Jira Issue BQS-6
Issue 4521: unicode/wstring issue Jira Issue BQS-7
Issue 4522: issue: move 'export' method Jira Issue BQS-8
Issue 4523: issue: a new (convenient) method Jira Issue BQS-9
Issue 4524: issue: adding properties to Journal Jira Issue BQS-10
Issue 4525: issue: text clarification (constraint language) Jira Issue BQS-11
Issue 4526: issue: renaming subject heading Jira Issue BQS-12
Issue 4527: issue: adding the source of subject headings Jira Issue BQS-13
Issue 4546: issue: excluded attributes Jira Issue BQS-14
Issue 4826: Figure 2-1/Bibliographic Query Service 1.0 issue Jira Issue BQS-1
Issue 4124: particular valuetype inheritance is truncatable. (bqs-ftf)
Click here for this issue's archive.
Source: David Frankel Consulting (Mr. David Frankel, david(at)dfrankelconsulting.com)
Nature: Uncategorized Issue
Severity:
Summary:
The UML model on page 18 uses the OMG UML Profile for CORBA. It does not use the capability of that profile to indicate that a particular valuetype inheritance is truncatable.
Apply the stereotype <<CORBATruncatable>> to the generalization in all cases where the generalization depicts truncatable inheritance.
The UML model on page 18 does not specify multiplicities on both ends of associations.
PROPOSAL Decide what the multiplicities should be and add them to the model. The current diagram is sufficient for the illustrative purposes
This AB member asked the author during the AB meeting whether the UML diagram is intended to be normative. For example, multiplicities on references are 0..1 in some cases and 1 in other cases, indicating in the former cases that a null value is acceptable and in the latter cases that a null value is not acceptable. The question is whether the author intended such specifications of multiplicity and other semantics in the UML diagram to be normative. The author answered that they are intended to be normative. However, the document calls the diagram "illustrative."
PROPOSAL If in fact the semantics in the UML diagram are supposed to be normative, the specification should say so clearly. The author was wrong. The UML was, indeed, intended to be illustrative. The normative is only IDL. However, and this was the author's intention, when exporting citations in the XML form, and if the repository does not provide its own XML model (a DTD), then the UML diagram shown in the spec should be taken and an appropriate XMI generated and used normatively
The author indicates that the UML is intended to be normative, but the submission does not provide an XMI representation of the UML model. An XMI representation of a UML model has the benefit of providing a precise, linear rendering of all the properties of the model using the official OMG XMI DTD for UML.
PROPOSAL Include an XMI document representing the UML model. Most UML tools now can generate an XMI document to represent a UML model.
Repository introspection mechanism allows to find what attributes are available in the repository. But the attributes play two roles: they can be used in queries (query-able attributes) and they can be just return back in the retrieved citations (usually the first role is a subset of the latter one). There is no interoperable way how to find what role which attribute plays. Resolution: To add to DsLSRBibQuery module: const string ROLE_ATTR_QUERYABLE = "queryable"; const string ROLE_ATTR_RETRIEVABLE = "retrievable"; And to explain in the text that these strings could/should appear in the 'description' field of the controlled vocabularies with attributes.
To add to the DsLSRBibQuery module: const string ROLE_ATTR_QUERYABLE = "queryable"; const string ROLE_ATTR_RETRIEVABLE = "retrievable"; To add to the document: The introspection mechanism allows to find what attributes are available in the repository. The attributes, however, play two roles: they can be used in query methods (query-able attributes) and/or they can be returned back in the retrieved citations (very often the first role is a subset of the latter one). In order to achieve an interoperable way how to find the attribute roles there are two predefined constants: const string ROLE_ATTR_QUERYABLE = "queryable"; const string ROLE_ATTR_RETRIEVABLE = "retrievable"; The constants above are advised to be used anywhere in the description field of a controlled vocabulary entry describing an attribute
Bibliographic repositories may deal with citations using non-ascii characters (for example MEDLINE is using unicode for foreign characters). Sending such strings using IDL type 'string' will result in a CORBA exception (character encoding error, or something like that). The problem is not with attributes stored and sent in the dynamic properties - they are wrapped in CORBA Anys, and therefore may be encoded using IDL type 'wstring' without changing BQS IDL - but the problem is with explicitly specified attributes. Resolution: To change the type of the following attributes (and typedefs) from 'string' to 'wstring': - in DsLSRBibObjects module: Keywords, surname, first_name, mid_initials, postal_address, affiliation, name (in Organisation, Service, and Journal), the_abstract, table_of_contents, title - in DsLSRBibQuery module: PhraseList
Method 'export' in interface BibRefUtilities is, indeed, a utility method (converting given citation into an XML representation). However, the format of XML used may be (and usually is) dependent on the collection/repository where the citation comes from. Therefore, it is much easier and more logical to have this method in the BibRefCollection interface (as we found during the implementation). Resolution: To move the 'export' method from interface BibRefUtilities to the interface BibRefCollection (both in module DsLSRBibQuery).
To move the export method from interface BibRefUtilities to the interface BibRefCollection (both interfaces are in module DsLSRBibQuery). To move also the explanatory text, and to change the text slightly (the text in square brackets remains unchanged): [This method converts a bibliographic reference into an XML representation using the same rules as exporter methods in BibRefCollection] representing a query collection where the_citation comes from.
During BQS implementation we found that a convenient method retrieving only identifiers of the citations from the query collection would dramatically improve the performance and make the implementation easier. It is, indeed, a convenient method, not a new functionality - because the same can be achieved by creating a collection using a list of 'excluded' attributes. Such list would need to contain _all_ attributes except of an identifier which may not be so easy to implement (both on server and client side). Also, it would require to create always a new collection just for the purpose of retrieving pure identifiers. To have this convenient method make simply life easier. Resolution: To add a new method into module DsLSRBibQuery in the interface BibRefCollection: DsLSRBibObjects::BibRefIdentifierList retrieve_all_ids() raises (LimitExceeded);
To add a new method into the module DsLSRBibQuery in the interface BibRefCollection: DsLSRBibObjects::BibRefIdentifierList retrieve_all_ids() raises (LimitExceeded); To add the following text to tyhe chapter 2.2.9 "Retrieving citations": It returns a list of identifiers of all bibliographic references from a given collection. An implementation can raise a LimitExceeded exception if the number of returned identifiers causes problems.
The BQS spec says (in 2.1.6.4 Journal) that "the rest are accessible using dynamic properties" but, unfortunately, the Properties attribute is missing in the IDL. It is a typo. Resolution: To add the following property attribute to the valuetype Journal in module DsLSRBibObjects: public CosPropertyService::Properties properties;
To add the following attribute to the valuetype Journal in module DsLSRBibObjects: public CosPropertyService::Properties properties;
The text in 2.2.8.3 (query by the constraint language) needs to be more precise when describing what 'params' can contain. The type of 'criteria' should be 'DsLSRControlledVocabularies::VocabularyStringList', and "the implementation uses these parameters in the same way" is not completely correct because criteria cannot be sent back (the 'params' is not an inout parametr, as in the 'find' method).
During our implementation it became obvious that name 'subheading' is confusing - because it may mean both sub-heading (a lower level heading), and a 'subject heading' (as used in cataloques as SEARS). For example, the MEDLINE uses the term MeSH for "medical subject headings", which has a descriptor (which is equivalent to BQS's subheading) and which has also a set of more detailed words called 'subheadings'. Confusing, isn't it? AFAIK, MEDLINE itself is going to change their naming of 'subheadings' to 'qualifiers' soon. Resolution: To change name 'subheading' to 'subject_heading'. Which means to have in DsLSRBibObject module this IDL: typedef string SubjectHeading; typedef sequence<SubjectHeading> SubjectHeadingList; ... valuetype BibRefSubject { public KeywordList keywords; public SubjectHeadingList subject_headings; public string subject_heading_collection; public ClassificationCodeList codes; };
The current spec says that the subject headings come from standard lists (e.g. SEARS, LCSH). But the spec does not have an attribute specifying this source. After consulting with the librarians and similar people, we found that this information is so important that it should qualify for having its own and explicit attribute. This is what was shown in the last resolution as public string subject_heading_collection; The contents of this attribute could be, for example, "SEARS", "MeSH", "LCSH". This, of course, opens the question why we are not suggesting the same for classification codes. We don't because we feel that classification codes are unique, they are more or less like identifers - and therefore they can be even expressed as identifiers using the same notation as with databases (source/id). But the subject headings are not necessarily unique: for example something like "MeSH/blahblah" can appear in several places in the MeSH trees) - and therefore using for that the pattern used for identifiers would not be appropriate. Therefore, the example just above would be coded as "blahblah" as one of the 'subject_heading' strings, and the word "MeSH" woud be in 'subject_heading_collection'. Resolution: To add subject_heading_collection (as shown already). To clarify documentation about differences between subject headings and classification codes, with a suggestion that for classification code may be used pattern for identifiers.
The BQS has a notion of the "excluded attributes". They can be specified in query methods and cause that the resulting collection has some attributes missing. The intention was to allow to create more lightweight collections (without long abstracts, for example). This reason is still valid and I am not going to ask to remove it from the query methods. However, during our implementation we found that also other "user pattern" is quite often: To create a collection, then ask for few attributes (like titles), and then ask for the another few attributes, and only that, finally, ask for the (whole) collection. The existence of excluded attributes in query methods makes it possible to realize such pattern - but the implementation become quite complex. Because whenever the user wants to change the set of excluded attributes, the server has to create a new collection (which may be optimalized, I know, but still it is a hassle for the implementation). Therefore, I am thinking about adding the "excluded attributes" parameter also to the retrieval methods. I would not expect big problems from the FTF's P&P point of view, because I hope that I can prove that adding such parameter is not new functionality but only a convenient way how to achieve already existing functions. However, I would like to ask for your advice, if this addition is or is not bad from the BQS architecture point of view. I know that our implementation (and perhaps other implementations as well) would be much cleaner with having these attributes, but is that enough to justify the suggested change? Resolution (would be): To add a parameter "in AttributeList excluded" to the retrival methods (all in BibRefCollection interface): - retrieve_all_elements() - create_iterator() - find_by_id()
This arose from the AB review of dtc/01-12-03. Figure 2-1 is wrong to apply the <<CORBATruncatable>> stereotype to classes: according to the UML Profile for CORBA 1.1 this stereotype should be applied to Generalizations only. Moreover there is no such stereotype <<CORBAValuetype>> - it should be <<CORBAValue>>. This is not a major issue since the diagrams are not normative and the IDL is OK - however I think it's desirable to fix it since it could perpetuate misunderstanding.