`docutils.nodesdocument)}( rawsourcechildren](hraw)}(h\newpageh]hText\newpage}(hhparenth uba attributes}(ids]classes]names]dupnames]backrefs]formatlatex xml:spacepreserveutagnameh source_/var/lib/jenkins/jobs/Metacat_stable/workspace/metacat/docs/user/metacat/source/identifiers.rstlineKhhhhubhsection)}(hhh](htitle)}(hIdentifier Managementh]hIdentifier Management}(hh3hh1hhh'Nh)Nubah}(h]h]h]h]h ]uh&h/hh,hhh'h(h)Kubsphinx.addnodesindex)}(hhh]h}(h]h]h]h]h ]entries](single Identifiersindex-0hNtainlineuh&h@h'h(h)K hh,hhubhtarget)}(hhh]h}(h]h]h]h]h ]refidhOuh&hRhh,hhh'h(h)K ubhdefinition_list)}(hhh](hdefinition_list_item)}(hAuthor Matthew B. Jones h](hterm)}(hAuthorh]hAuthor}(hhmhhkubah}(h]h]h]h]h ]uh&hih'h(h)K hheubh definition)}(hhh]h paragraph)}(hMatthew B. Jonesh]hMatthew B. Jones}(hhhhubah}(h]h]h]h]h ]uh&h~h'h(h)K hh{ubah}(h]h]h]h]h ]uh&hyhheubeh}(h]h]h]h]h ]uh&hch'h(h)K hh`ubhd)}(h@Date - 20100301 [MBJ] Initial draft of Identifier documentation h](hj)}(hDateh]hDate}(hhhhubah}(h]h]h]h]h ]uh&hih'h(h)Khhubhz)}(hhh]h bullet_list)}(hhh]h list_item)}(h920100301 [MBJ] Initial draft of Identifier documentation h]h)}(h820100301 [MBJ] Initial draft of Identifier documentationh]h820100301 [MBJ] Initial draft of Identifier documentation}(hhhhubah}(h]h]h]h]h ]uh&h~h'h(h)Khhubah}(h]h]h]h]h ]uh&hhhubah}(h]h]h]h]h ]bullet-uh&hh'h(h)Khhubah}(h]h]h]h]h ]uh&hyhhubeh}(h]h]h]h]h ]uh&hch'h(h)Khh`hhubhd)}(hAGoal Extend Metacat to support identifiers with arbitrary syntax h](hj)}(hGoalh]hGoal}(hhhhubah}(h]h]h]h]h ]uh&hih'h(h)Khhubhz)}(hhh]h)}(h;Extend Metacat to support identifiers with arbitrary syntaxh]h;Extend Metacat to support identifiers with arbitrary syntax}(hhhhubah}(h]h]h]h]h ]uh&h~h'h(h)Khhubah}(h]h]h]h]h ]uh&hyhhubeh}(h]h]h]h]h ]uh&hch'h(h)Khh`hhubhd)}(hXSummary Metacat currently supports identifier strings called 'docids' that have the syntax 'scope.object.revision', such as 'foo.34.1' (we will refer to these as 'LocalIDs'). We now want Metacat to support identifiers that are arbitrary strings, but still enforce uniqueness and proper revision handling (refer to these as GUIDs). Metacat must be able to accept these strings as identifiers for all CRUD operations, and reference them in search results. h](hj)}(hSummaryh]hSummary}(hjhjubah}(h]h]h]h]h ]uh&hih'h(h)Khjubhz)}(hhh]h)}(hXMetacat currently supports identifier strings called 'docids' that have the syntax 'scope.object.revision', such as 'foo.34.1' (we will refer to these as 'LocalIDs'). We now want Metacat to support identifiers that are arbitrary strings, but still enforce uniqueness and proper revision handling (refer to these as GUIDs). Metacat must be able to accept these strings as identifiers for all CRUD operations, and reference them in search results.h]hXMetacat currently supports identifier strings called ‘docids’ that have the syntax ‘scope.object.revision’, such as ‘foo.34.1’ (we will refer to these as ‘LocalIDs’). We now want Metacat to support identifiers that are arbitrary strings, but still enforce uniqueness and proper revision handling (refer to these as GUIDs). Metacat must be able to accept these strings as identifiers for all CRUD operations, and reference them in search results.}(hj(hj&ubah}(h]h]h]h]h ]uh&h~h'h(h)Khj#ubah}(h]h]h]h]h ]uh&hyhjubeh}(h]h]h]h]h ]uh&hch'h(h)Khh`hhubeh}(h]hOah]h]h]h ]uh&h^hh,hhh'h(h)Nexpect_referenced_by_name}expect_referenced_by_id}hOhTsubh+)}(hhh](h0)}(hIdentifier Resolutionh]hIdentifier Resolution}(hjOhjMhhh'Nh)Nubah}(h]h]h]h]h ]uh&h/hjJhhh'h(h)Kubh)}(hXBecause Metacat uses LocalIDs throughout the code for references to objects, and that LocalID has a constrained structure that includes semantics about revisions in the identifier, it is difficult to wholesale replace it with less-constrained string identifiers without re-writing much of Metacat. Thus, our alternate strategy is to wrap the Metacat APIs with a identifier resolution layer that keeps track of the unconstrained GUIDs and maps them to constrained local identifiers which are used internally within Metacat. The basic identifer table model is shown in Figure 1, while the basic strategy for retrieving an object is shown in Figure 2, creating an object is shown in Figure 3, updating an object in Figure 4, and deleting an object is shown in Figure 5.h]hXBecause Metacat uses LocalIDs throughout the code for references to objects, and that LocalID has a constrained structure that includes semantics about revisions in the identifier, it is difficult to wholesale replace it with less-constrained string identifiers without re-writing much of Metacat. Thus, our alternate strategy is to wrap the Metacat APIs with a identifier resolution layer that keeps track of the unconstrained GUIDs and maps them to constrained local identifiers which are used internally within Metacat. The basic identifer table model is shown in Figure 1, while the basic strategy for retrieving an object is shown in Figure 2, creating an object is shown in Figure 3, updating an object in Figure 4, and deleting an object is shown in Figure 5.}(hj]hj[hhh'Nh)Nubah}(h]h]h]h]h ]uh&h~h'h(h)KhjJhhubh+)}(hhh](h0)}(hIdentifier Table Structureh]hIdentifier Table Structure}(hjnhjlhhh'Nh)Nubah}(h]h]h]h]h ]uh&h/hjihhh'h(h)K-ubhfigure)}(hhh](himage)}(hR.. figure:: images/identifiers.png Figure 1. Table structure for identifiers. h]h}(h]h]h]h]h ]uriimages/identifiers.png candidates}*jsuh&jhj|h'h(h)K1ubhcaption)}(h*Figure 1. Table structure for identifiers.h]h*Figure 1. Table structure for identifiers.}(hjhjubah}(h]h]h]h]h ]uh&jh'h(h)K1hj|ubeh}(h]id1ah]h]h]h ]uh&jzh)K1hjihhh'h(ubhcomment)}(hXThis block defines the table structure diagram referenced above. @startuml images/identifiers.png identifiers "*" -- "1" xml_documents identifiers : String identifier identifiers : String docid identifiers : Integer rev xml_documents : String docid xml_documents : String rev note right of identifiers "identifiers.(docid,rev) is a foreign key into xml_documents" end note @endumlh]hXThis block defines the table structure diagram referenced above. @startuml images/identifiers.png identifiers "*" -- "1" xml_documents identifiers : String identifier identifiers : String docid identifiers : Integer rev xml_documents : String docid xml_documents : String rev note right of identifiers "identifiers.(docid,rev) is a foreign key into xml_documents" end note @enduml}(hhhjubah}(h]h]h]h]h ]h$h%uh&jhjihhh'h(h)KDubh )}(h\newpageh]h\newpage}(hhhjubah}(h]h]h]h]h ]formatlatexh$h%uh&h h'h(h)KEhjihhubh )}(h PageBreakh]h PageBreak}(hhhjubah}(h]h]h]h]h ]formatpdfh$h%uh&h h'h(h)KIhjihhubeh}(h]identifier-table-structureah]h]identifier table structureah]h ]uh&h*hjJhhh'h(h)K-ubh+)}(hhh](h0)}(h!Handling document read operationsh]h!Handling document read operations}(hjhjhhh'Nh)Nubah}(h]h]h]h]h ]uh&h/hjhhh'h(h)KOubh)}(hAAn overview of the process needed to read an object using a GUID.h]hAAn overview of the process needed to read an object using a GUID.}(hjhjhhh'Nh)Nubah}(h]h]h]h]h ]uh&h~h'h(h)KQhjhhubj{)}(hhh](j)}(h.. figure:: images/guid_read.png Figure 2. Basic handling for string identifiers (GUIDs) as mapped to docids (LocalIDs) to retrieve an object. h]h}(h]h]h]h]h ]uriimages/guid_read.pngj}jj suh&jhjh'h(h)KVubj)}(hmFigure 2. Basic handling for string identifiers (GUIDs) as mapped to docids (LocalIDs) to retrieve an object.h]hmFigure 2. Basic handling for string identifiers (GUIDs) as mapped to docids (LocalIDs) to retrieve an object.}(hjhjubah}(h]h]h]h]h ]uh&jh'h(h)KVhjubeh}(h]id2ah]h]h]h ]uh&jzh)KVhjhhh'h(ubj)}(hX@startuml images/guid_read.png !include plantuml.conf actor User participant "Client" as app_client << Application >> participant "CRUD API" as c_crud << MetacatRestServlet >> participant "Identifier Manager" as ident_man << IdentifierManager >> participant "Handler" as handler << MetacatHandler >> User -> app_client app_client -> c_crud: get(token, GUID) c_crud -> ident_man: getLocalID(GUID) c_crud <-- ident_man: localID c_crud -> handler: handleReadAction(localID) c_crud <-- handler: object c_crud --> app_client: object @endumlh]hX@startuml images/guid_read.png !include plantuml.conf actor User participant "Client" as app_client << Application >> participant "CRUD API" as c_crud << MetacatRestServlet >> participant "Identifier Manager" as ident_man << IdentifierManager >> participant "Handler" as handler << MetacatHandler >> User -> app_client app_client -> c_crud: get(token, GUID) c_crud -> ident_man: getLocalID(GUID) c_crud <-- ident_man: localID c_crud -> handler: handleReadAction(localID) c_crud <-- handler: object c_crud --> app_client: object @enduml}(hhhj#ubah}(h]h]h]h]h ]h$h%uh&jhjhhh'h(h)Kjubeh}(h]!handling-document-read-operationsah]h]!handling document read operationsah]h ]uh&h*hjJhhh'h(h)KOubh+)}(hhh](h0)}(h#Handling document create operationsh]h#Handling document create operations}(hj>hj<hhh'Nh)Nubah}(h]h]h]h]h ]uh&h/hj9hhh'h(h)Klubh)}(hCAn overview of the process needed to create an object using a GUID.h]hCAn overview of the process needed to create an object using a GUID.}(hjLhjJhhh'Nh)Nubah}(h]h]h]h]h ]uh&h~h'h(h)Knhj9hhubj{)}(hhh](j)}(h.. figure:: images/guid_insert.png Figure 3. Basic handling for string identifiers (GUIDs) as mapped to docids (LocalIDs) to create an object. h]h}(h]h]h]h]h ]uriimages/guid_insert.pngj}jjfsuh&jhjXh'h(h)Krubj)}(hkFigure 3. Basic handling for string identifiers (GUIDs) as mapped to docids (LocalIDs) to create an object.h]hkFigure 3. Basic handling for string identifiers (GUIDs) as mapped to docids (LocalIDs) to create an object.}(hjjhjhubah}(h]h]h]h]h ]uh&jh'h(h)KrhjXubeh}(h]id3ah]h]h]h ]uh&jzh)Krhj9hhh'h(ubj)}(hX{@startuml images/guid_insert.png !include plantuml.conf actor User participant "Client" as app_client << Application >> participant "CRUD API" as c_crud << MetacatRestServlet >> participant "Identifier Manager" as ident_man << IdentifierManager >> participant "Handler" as handler << MetacatHandler >> User -> app_client app_client -> c_crud: create(token, GUID, object, sysmeta) c_crud -> ident_man: identifierExists(GUID) c_crud <-- ident_man: T or F alt identifierExists == "F" c_crud -> ident_man: mapToLocalId(GUID) c_crud <-- ident_man: localID c_crud -> handler: handleInsertAction(localID) c_crud <-- handler: success note right of c_crud "Also need to address how to handle the sysmeta information wrt insertion methods" end note app_client <-- c_crud: success else identifierExists == "T" app_client <-- c_crud: IdentifierNotUnique end @endumlh]hX{@startuml images/guid_insert.png !include plantuml.conf actor User participant "Client" as app_client << Application >> participant "CRUD API" as c_crud << MetacatRestServlet >> participant "Identifier Manager" as ident_man << IdentifierManager >> participant "Handler" as handler << MetacatHandler >> User -> app_client app_client -> c_crud: create(token, GUID, object, sysmeta) c_crud -> ident_man: identifierExists(GUID) c_crud <-- ident_man: T or F alt identifierExists == "F" c_crud -> ident_man: mapToLocalId(GUID) c_crud <-- ident_man: localID c_crud -> handler: handleInsertAction(localID) c_crud <-- handler: success note right of c_crud "Also need to address how to handle the sysmeta information wrt insertion methods" end note app_client <-- c_crud: success else identifierExists == "T" app_client <-- c_crud: IdentifierNotUnique end @enduml}(hhhj}ubah}(h]h]h]h]h ]h$h%uh&jhj9hhh'h(h)Kubeh}(h]#handling-document-create-operationsah]h]#handling document create operationsah]h ]uh&h*hjJhhh'h(h)Klubh+)}(hhh](h0)}(h#Handling document update operationsh]h#Handling document update operations}(hjhjhhh'Nh)Nubah}(h]h]h]h]h ]uh&h/hjhhh'h(h)Kubh)}(hCAn overview of the process needed to update an object using a GUID.h]hCAn overview of the process needed to update an object using a GUID.}(hjhjhhh'Nh)Nubah}(h]h]h]h]h ]uh&h~h'h(h)Khjhhubj{)}(hhh](j)}(h.. figure:: images/guid_update.png Figure 4. Basic handling for string identifiers (GUIDs) as mapped to docids (LocalIDs) to update an object. h]h}(h]h]h]h]h ]uriimages/guid_update.pngj}jjsuh&jhjh'h(h)Kubj)}(hkFigure 4. Basic handling for string identifiers (GUIDs) as mapped to docids (LocalIDs) to update an object.h]hkFigure 4. Basic handling for string identifiers (GUIDs) as mapped to docids (LocalIDs) to update an object.}(hjhjubah}(h]h]h]h]h ]uh&jh'h(h)Khjubeh}(h]id4ah]h]h]h ]uh&jzh)Khjhhh'h(ubj)}(hX@startuml images/guid_update.png !include plantuml.conf actor User participant "Client" as app_client << Application >> participant "CRUD API" as c_crud << MetacatRestServlet >> participant "Identifier Manager" as ident_man << IdentifierManager >> participant "Handler" as handler << MetacatHandler >> User -> app_client app_client -> c_crud: update(token, GUID, object, obsoletedGUID, sysmeta) c_crud -> ident_man: identifierExists(obsoletedGUID) c_crud <-- ident_man: T or F alt identifierExists == "T" c_crud -> ident_man: identifierExists(GUID) c_crud <-- ident_man: T or F alt identifierExists == "F" c_crud -> ident_man: mapToLocalId(GUID, obsoletedGUID) c_crud <-- ident_man: localID c_crud -> handler: handleUpdateAction(localID) c_crud <-- handler: success note right of c_crud "Also need to address how to handle the sysmeta information wrt update methods" end note app_client <-- c_crud: success else identifierExists == "T" app_client <-- c_crud: IdentifierNotUnique end else identifierExists == "F" app_client <-- c_crud: NotFound end @endumlh]hX@startuml images/guid_update.png !include plantuml.conf actor User participant "Client" as app_client << Application >> participant "CRUD API" as c_crud << MetacatRestServlet >> participant "Identifier Manager" as ident_man << IdentifierManager >> participant "Handler" as handler << MetacatHandler >> User -> app_client app_client -> c_crud: update(token, GUID, object, obsoletedGUID, sysmeta) c_crud -> ident_man: identifierExists(obsoletedGUID) c_crud <-- ident_man: T or F alt identifierExists == "T" c_crud -> ident_man: identifierExists(GUID) c_crud <-- ident_man: T or F alt identifierExists == "F" c_crud -> ident_man: mapToLocalId(GUID, obsoletedGUID) c_crud <-- ident_man: localID c_crud -> handler: handleUpdateAction(localID) c_crud <-- handler: success note right of c_crud "Also need to address how to handle the sysmeta information wrt update methods" end note app_client <-- c_crud: success else identifierExists == "T" app_client <-- c_crud: IdentifierNotUnique end else identifierExists == "F" app_client <-- c_crud: NotFound end @enduml}(hhhjubah}(h]h]h]h]h ]h$h%uh&jhjhhh'h(h)Kubeh}(h]#handling-document-update-operationsah]h]#handling document update operationsah]h ]uh&h*hjJhhh'h(h)Kubh+)}(hhh](h0)}(h#Handling document delete operationsh]h#Handling document delete operations}(hjhjhhh'Nh)Nubah}(h]h]h]h]h ]uh&h/hjhhh'h(h)Kubh)}(hCAn overview of the process needed to delete an object using a GUID.h]hCAn overview of the process needed to delete an object using a GUID.}(hjhjhhh'Nh)Nubah}(h]h]h]h]h ]uh&h~h'h(h)Khjhhubj{)}(hhh](j)}(h.. figure:: images/guid_delete.png Figure 5. Basic handling for string identifiers (GUIDs) as mapped to docids (LocalIDs) to delete an object. h]h}(h]h]h]h]h ]uriimages/guid_delete.pngj}jjsuh&jhj h'h(h)Kubj)}(hkFigure 5. Basic handling for string identifiers (GUIDs) as mapped to docids (LocalIDs) to delete an object.h]hkFigure 5. Basic handling for string identifiers (GUIDs) as mapped to docids (LocalIDs) to delete an object.}(hjhjubah}(h]h]h]h]h ]uh&jh'h(h)Khj ubeh}(h]id5ah]h]h]h ]uh&jzh)Khjhhh'h(ubj)}(hX@startuml images/guid_delete.png !include plantuml.conf actor User participant "Client" as app_client << Application >> participant "CRUD API" as c_crud << MetacatRestServlet >> participant "Identifier Manager" as ident_man << IdentifierManager >> participant "Handler" as handler << MetacatHandler >> User -> app_client app_client -> c_crud: delete(token, GUID) c_crud -> ident_man: identifierExists(GUID) c_crud <-- ident_man: T or F alt identifierExists == "T" c_crud -> ident_man: mapToLocalId(GUID) c_crud <-- ident_man: localID c_crud -> handler: handleDeleteAction(localID) c_crud <-- handler: success app_client <-- c_crud: success else identifierExists == "F" app_client <-- c_crud: NotFound end @endumlh]hX@startuml images/guid_delete.png !include plantuml.conf actor User participant "Client" as app_client << Application >> participant "CRUD API" as c_crud << MetacatRestServlet >> participant "Identifier Manager" as ident_man << IdentifierManager >> participant "Handler" as handler << MetacatHandler >> User -> app_client app_client -> c_crud: delete(token, GUID) c_crud -> ident_man: identifierExists(GUID) c_crud <-- ident_man: T or F alt identifierExists == "T" c_crud -> ident_man: mapToLocalId(GUID) c_crud <-- ident_man: localID c_crud -> handler: handleDeleteAction(localID) c_crud <-- handler: success app_client <-- c_crud: success else identifierExists == "F" app_client <-- c_crud: NotFound end @enduml}(hhhj1ubah}(h]h]h]h]h ]h$h%uh&jhjhhh'h(h)Kubj)}(hXNThis block defines the interaction diagram referenced above. startuml images/01_interaction.png !include plantuml.conf actor User participant "Client" as app_client << Application >> User -> app_client participant "CRUD API" as c_crud << Coordinating Node >> activate c_crud app_client -> c_crud: resolve(GUID, auth_token) participant "Authorization API" as c_authorize << Coordinating Node >> c_crud -> c_authorize: isAuth(auth_token, GUID) participant "Verify API" as c_ver << Coordinating Node >> c_authorize -> c_ver: isValidToken (token) c_authorize <-- c_ver: T or F c_crud <-- c_authorize: T or F app_client <-- c_crud: handle_list deactivate c_crud participant "CRUD API" as m_crud << Member Node >> activate m_crud app_client -> m_crud: get(auth_token, handle) participant "Server Authentication API" as m_authenticate << Member Node >> m_crud -> m_authenticate: isAuth(auth_token, GUID) m_crud <-- m_authenticate: T or F m_crud -> m_crud: log(get, UserID, GUID) app_client <-- m_crud: object or unauth or doesNotExist deactivate m_crud endumlh]hXNThis block defines the interaction diagram referenced above. startuml images/01_interaction.png !include plantuml.conf actor User participant "Client" as app_client << Application >> User -> app_client participant "CRUD API" as c_crud << Coordinating Node >> activate c_crud app_client -> c_crud: resolve(GUID, auth_token) participant "Authorization API" as c_authorize << Coordinating Node >> c_crud -> c_authorize: isAuth(auth_token, GUID) participant "Verify API" as c_ver << Coordinating Node >> c_authorize -> c_ver: isValidToken (token) c_authorize <-- c_ver: T or F c_crud <-- c_authorize: T or F app_client <-- c_crud: handle_list deactivate c_crud participant "CRUD API" as m_crud << Member Node >> activate m_crud app_client -> m_crud: get(auth_token, handle) participant "Server Authentication API" as m_authenticate << Member Node >> m_crud -> m_authenticate: isAuth(auth_token, GUID) m_crud <-- m_authenticate: T or F m_crud -> m_crud: log(get, UserID, GUID) app_client <-- m_crud: object or unauth or doesNotExist deactivate m_crud enduml}(hhhj?ubah}(h]h]h]h]h ]h$h%uh&jhjhhh'h(h)Kubeh}(h]#handling-document-delete-operationsah]h]#handling document delete operationsah]h ]uh&h*hjJhhh'h(h)Kubeh}(h]identifier-resolutionah]h]identifier resolutionah]h ]uh&h*hh,hhh'h(h)Kubeh}(h]identifier-managementah]h]identifier managementah]h ]uh&h*hhhhh'h(h)Kubeh}(h]h]h]h]h ]sourceh(uh&hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(h/N generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingUTF-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh( _destinationN _config_files]pep_referencesN pep_base_url https://www.python.org/dev/peps/pep_file_url_templatepep-%04drfc_referencesN rfc_base_urlhttps://tools.ietf.org/html/ tab_widthKtrim_footnote_reference_spacefile_insertion_enabled raw_enabledKsyntax_highlightlong smart_quotessmartquotes_localesNcharacter_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xformembed_stylesheetcloak_email_addressesenvNgettext_compactubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}hO]hTasnameids}(jbj_jZjWjjj6j3jjjjjRjOu nametypes}(jbNjZNjNj6NjNjNjRNuh}(j_h,hOh`jWjJjjij3jjj9jjjOjjj|jjjxjXjjj,j u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startKid_startKparse_messages]transform_messages]hsystem_message)}(hhh]h)}(hhh]h-Hyperlink target "index-0" is not referenced.}(hhhjubah}(h]h]h]h]h ]uh&h~hjubah}(h]h]h]h]h ]levelKtypeINFOsourceh(lineK uh&juba transformerN decorationNhhub.