Project

General

Profile

1 5266 jones
.. raw:: latex
2
3
  \newpage
4
5
6
Identifier Management
7
---------------------
8
9
.. index:: Identifiers
10
11
Author
12
  Matthew B. Jones
13
14
Date
15
  - 20100301 [MBJ] Initial draft of Identifier documentation
16
17
Version
18
  1.9.2
19
20
Goal
21
  Extend Metacat to support identifiers with arbitrary syntax
22
23
Summary
24
  Metacat currently supports identifier strings called 'docids' that have
25
  the syntax 'scope.object.revision', such as 'foo.34.1' (we will refer to
26
  these as 'LocalIDs'). We now want Metacat to support identifiers that are
27
  arbitrary strings, but still enforce uniqueness and proper revision
28
  handling (referred to these as GUIDs).  Metacat must be able to accept
29
  these strings as identifiers for all CRUD operations, and reference them
30
  in search results.
31
32
Identifier Resolution
33
=====================
34
Because Metacat uses LocalIDs throughout the code for references to objects,
35
and that LocalID has a constrained structure that includes semantics about
36
revisions in the identifier, it is difficult to wholesale replace it with
37
less-constrained string identifiers without re-writing much of Metacat.
38
Thus, our alternate strategy would is to wrap the Metacat APIs with a
39
identifier resolution layer that keeps track of the unconstrained GUIDs and
40
maps them to constrained local identifiers which are used internally within
41
Metacat. The basic identifer table model is shown in Figure 1, while the
42
basic strategy for retrieving an object is shown in Figure 2.
43
44
45
Identifier Table Structure
46
~~~~~~~~~~~~~~~~~~~~~~~~~~
47
48
.. figure:: images/identifiers.png
49
50
   Figure 1. Table structure for identifiers.
51
52
..
53
  This block defines the table structure diagram referenced above.
54
  @startuml images/identifiers.png
55
56
  identifiers "*" -- "1" xml_documents
57
58
  identifiers : String identifier
59
  identifiers : String docid
60
  identifiers : Integer rev
61
62
  xml_documents : String docid
63
  xml_documents : String rev
64
65
  note right of identifiers
66
    "identifiers.(docid,rev) is a foreign key into xml_documents"
67
  end note
68
  @enduml
69
70
.. raw:: latex
71
72
  \newpage
73
74
.. raw:: pdf
75
76
  PageBreak
77
78
79
Handling document read operations
80
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
81
82
An overview of the process needed to read an object using a GUID.
83
84
85
.. figure:: images/guid_read.png
86
87
   Figure 2. Basic handling for string identifiers (GUIDs) as mapped to
88
   docids (LocalIDs) to retrieve an object.
89
90
..
91
  @startuml images/guid_read.png
92
  !include plantuml.conf
93
  actor User
94
  participant "Client" as app_client << Application >>
95
  participant "CRUD API" as c_crud << MetacatRestServlet >>
96
  participant "Identifier Manager" as ident_man << IdentifierManager >>
97
  participant "Handler" as handler << MetacatHandler >>
98
  User -> app_client
99
  app_client -> c_crud: get(token, GUID)
100
  c_crud -> ident_man: getLocalID(GUID)
101
  c_crud <-- ident_man: localID
102
  c_crud -> handler: handleReadAction(localID)
103
  c_crud <-- handler: object
104
  c_crud --> app_client: object
105
106
  @enduml
107
108
Handling document create operations
109
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
110
111
An overview of the process needed to create an object using a GUID.
112
113
.. figure:: images/guid_insert.png
114
115
   Figure 3. Basic handling for string identifiers (GUIDs) as mapped to
116
   docids (LocalIDs) to create an object.
117
118
..
119
  @startuml images/guid_insert.png
120
  !include plantuml.conf
121
  actor User
122
  participant "Client" as app_client << Application >>
123
  participant "CRUD API" as c_crud << MetacatRestServlet >>
124
  participant "Identifier Manager" as ident_man << IdentifierManager >>
125
  participant "Handler" as handler << MetacatHandler >>
126
  User -> app_client
127
  app_client -> c_crud: create(token, GUID, object, sysmeta)
128
  c_crud -> ident_man: identifierExists(GUID)
129
  c_crud <-- ident_man: T or F
130
  alt identifierExists == "F"
131
      c_crud -> ident_man: mapToLocalId(GUID)
132
      c_crud <-- ident_man: localID
133
      c_crud -> handler: handleInsertAction(localID)
134
      c_crud <-- handler: success
135
      note right of c_crud
136
        "Also need to address how to handle the sysmeta information wrt insertion methods"
137
      end note
138
      app_client <-- c_crud: success
139
  else identifierExists == "T"
140
      app_client <-- c_crud: IdentifierNotUnique
141
  end
142
  @enduml
143
144
Handling document update operations
145
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
146
147
An overview of the process needed to update an object using a GUID.
148
149
.. figure:: images/guid_update.png
150
151
   Figure 4. Basic handling for string identifiers (GUIDs) as mapped to
152
   docids (LocalIDs) to update an object.
153
154
..
155
  @startuml images/guid_update.png
156
  !include plantuml.conf
157
  actor User
158
  participant "Client" as app_client << Application >>
159
  participant "CRUD API" as c_crud << MetacatRestServlet >>
160
  participant "Identifier Manager" as ident_man << IdentifierManager >>
161
  participant "Handler" as handler << MetacatHandler >>
162
  User -> app_client
163
  app_client -> c_crud: update(token, GUID, object, obsoletedGUID, sysmeta)
164
165
  c_crud -> ident_man: identifierExists(obsoletedGUID)
166
  c_crud <-- ident_man: T or F
167
  alt identifierExists == "T"
168
169
      c_crud -> ident_man: identifierExists(GUID)
170
      c_crud <-- ident_man: T or F
171
      alt identifierExists == "F"
172
          c_crud -> ident_man: mapToLocalId(GUID, obsoletedGUID)
173
          c_crud <-- ident_man: localID
174
          c_crud -> handler: handleUpdateAction(localID)
175
          c_crud <-- handler: success
176
          note right of c_crud
177
            "Also need to address how to handle the sysmeta information wrt update methods"
178
          end note
179
          app_client <-- c_crud: success
180
      else identifierExists == "T"
181
          app_client <-- c_crud: IdentifierNotUnique
182
      end
183
  else identifierExists == "F"
184
      app_client <-- c_crud: NotFound
185
  end
186
  @enduml
187
188
Handling document delete operations
189
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
190
191
An overview of the process needed to delete an object using a GUID.
192
193
.. figure:: images/guid_delete.png
194
195
   Figure 5. Basic handling for string identifiers (GUIDs) as mapped to
196
   docids (LocalIDs) to delete an object.
197
198
..
199
  @startuml images/guid_delete.png
200
  !include plantuml.conf
201
  actor User
202
  participant "Client" as app_client << Application >>
203
  participant "CRUD API" as c_crud << MetacatRestServlet >>
204
  participant "Identifier Manager" as ident_man << IdentifierManager >>
205
  participant "Handler" as handler << MetacatHandler >>
206
  User -> app_client
207
  app_client -> c_crud: delete(token, GUID)
208
  c_crud -> ident_man: identifierExists(GUID)
209
  c_crud <-- ident_man: T or F
210
  alt identifierExists == "T"
211
      c_crud -> ident_man: mapToLocalId(GUID)
212
      c_crud <-- ident_man: localID
213
      c_crud -> handler: handleDeleteAction(localID)
214
      c_crud <-- handler: success
215
      app_client <-- c_crud: success
216
  else identifierExists == "F"
217
      app_client <-- c_crud: NotFound
218
  end
219
  @enduml
220
221
..
222
  This block defines the interaction diagram referenced above.
223
  startuml images/01_interaction.png
224
    !include plantuml.conf
225
    actor User
226
    participant "Client" as app_client << Application >>
227
    User -> app_client
228
229
    participant "CRUD API" as c_crud << Coordinating Node >>
230
    activate c_crud
231
    app_client -> c_crud: resolve(GUID, auth_token)
232
    participant "Authorization API" as c_authorize << Coordinating Node >>
233
    c_crud -> c_authorize: isAuth(auth_token, GUID)
234
    participant "Verify API" as c_ver << Coordinating Node >>
235
    c_authorize -> c_ver: isValidToken (token)
236
    c_authorize <-- c_ver: T or F
237
    c_crud <-- c_authorize: T or F
238
    app_client <-- c_crud: handle_list
239
    deactivate c_crud
240
241
    participant "CRUD API" as m_crud << Member Node >>
242
    activate m_crud
243
    app_client -> m_crud: get(auth_token, handle)
244
    participant "Server Authentication API" as m_authenticate << Member Node >>
245
    m_crud -> m_authenticate: isAuth(auth_token, GUID)
246
    m_crud <-- m_authenticate: T or F
247
    m_crud -> m_crud: log(get, UserID, GUID)
248
    app_client <-- m_crud: object or unauth or doesNotExist
249
    deactivate m_crud
250
  enduml