Issues for Bibliographic Query Service Finalization Task Force

List of issues (green=resolved, yellow=pending Board vote, red=unresolved)

List options: All ; Open Issues only; or Closed Issues only

Jira Issues

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)

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.