agents

					ai.do
Application Interface for DigitalObjects – Introduction

Class DigitalObject < Object

[OK – So tenous reasoning is “ai” is Japanese for “harmony”, “do” Japanese for “way” which
could be loosely translated to something like "the Way (do) to Harmony (ai) and chimes
nicely with Ruby way of aiming :), see below.]

General principles: High level, implementation independent, object oriented, simple, language
neutral (no preferred computing language), language native (naming and usage should
conform to target language practice)

Whereas DOI is currently implemented on top of Handle technology which provides a lookup
service to a set of typed data elements each uniquely identified by an index/type pairing, a
DigitalObject provides a linking mechanism between related data elements – DataGroups –
and applications that can meaningfully service the data elements within those DataGroups.

Handle selects data elements based on type and index value. A DigitalObject, on the other
hand, exists on a higher level and organizes DataGroups which are bound to specific
applications. A DataGroup can be selected based on a component element – typically that
element will be the application profile identifier which may be resolved to a data set affording
information on how to process (or more generally to interpret) the data elements.

Key differences: Handle provides for a persistent data storage (and access to that storage),
whereas a DigitalObject is a transient entity instantiated only within the lifetime of a
computational process. Handle transactions are at the data element level, whereas the
transactional “unit” for a DigitalObject is a DataGroup.

The content industries are necessarily focused on DigitalObjects – how the actual data
elements and their inter-relationships are persisted within a DataStore (ie accessed from a
disk drive, say) is not in scope. The DataStore, logically singular, may be physically singular
or multiple – from a DigitalObject perspective it is merely an abstraction. Application
processes need to interact directly with the DigitalObjects themselves and not with the low-
level DataStore. How the DataStore chooses to index, type, and otherwise organize the data
elements is irrelevant.

[Of course, there are compelling reasons for preferring one implementation over another:
robustness, scalability, speed, security, administration, etc. But the implementation (or
implementations) should above all be transparent to DigitalObject applications.]

What is needed is a simple API for accessing and manipulating DigitalObjects and their
DataGroups without reference to any underlying implementation. The API should be
responsible for fetching the data elements from the DataStore, organizing them into
DataGroups and binding those DataGroups to DigitalObject applications.

The following pages give examples of two trivial programs which make use of such an API,
together with their result sets, and then a reference for this API. Examples and reference are
expressed in the Ruby language for clarity. (A Java implementation would also be useful,
though necessarily a tad more long-winded ;-) These programs are run against a logical
DataStore – some of the values come from Handle, some from the Handle client YAHC. The
key point is that the implementations here are hidden from the API. Any registered DOI can
be accessed through this API.
Change History
This work builds on the draft document mailed out to the DOI lists “doi-discuss” (13.12.2000)
and “ref-links” (14.12.2000) and entitled: "Towards an Implementation of DOI Application
Profiles within the Handle System: A hierarchical architecture for DOI infrastructure". (A
revised draft with RDF dscriptions of the proposed schema was subsequently mailed out to
“ref-links”, 15.01.2001.) The following changes from those drafts are noted:

1. The DOI type “schemaDoc” is dropped. The type “schema” is sufficient.
2. The DOI type “description” is renamed “detail” – more mangeable and just as expressive
   – so contrast “10.type/label” and “10.type/detail”.
3. Per Larry L.‟s comment about unsuitability of the DOI profile “10.profile/null” (for
   “administrative” DOIs) being confused with “10.profile/zero” (for legacy DOIs without
   kernel metadata), I propose we renominate these as “10.profile/system” – thereby
   distinguishing between system-specific DOIs and application-specific DOIs, eg
   “10.profile/crossref”.
4. The RDF examples are deficient in that attributes cannot acquire a default namespacing,
   ie all attributes need to be prefixed with an “rdf:” namespace.
ai.do
Application Interface for DigitalObjects – Examples

Class DigitalObject < Object

Two example programs are listed below:

1. doi_data: This simply prints out for any DOI the types and values from the individual data
   elements, the DataGroups, as well as the kernel metadata (according to an early schema)
   and application-specific metadata.

2. doi_dataGroups: Just a trivial exercise in adding new DataGroups to a DigitalObject and
   rendering resource elements simply as a hyperlinked set of labels, with longer
   descriptions (DOI type „detail‟) presented as text for the browser status window on a
   Javascript „OnMouseOver‟ event. Not especially useful but should give some idea of the
   ease of manipulating DataGroups using such an API.
% cat doi_data
#!/export/home/tony/bin/ruby

require 'doi.rb'

doi = ARGV[0]             # Read DOI string from command line

d = DigitalObject.get(doi) # Create new instance and get values

######################################################################
#
# 1. Print the DOI Types and Values
#
######################################################################

puts ">> Data types for doi:#{doi}:\n", d.dataTypes, "\n"
puts ">> Data values for doi:#{doi}:\n", d.dataValues, "\n"

######################################################################
#
# 2. Print a dump of the DOI Data Groups
#
######################################################################

puts ">> Data groups for doi:#{doi}:\n"; d.dataGroupsDump

######################################################################
#
# 3. Print the DOI Application Profiles, and Metadata – Kernel
#    and Application Profile
#
######################################################################

puts ">> Application profiles for doi:#{doi}:\n", d.profiles, "\n"

d.profiles.each do |p|

  puts ">> Kernel metadata for doi:#{doi}:\n", d.kernelMetadata(p), "\n"
  puts ">> Profile metadata for doi:#{doi}:\n", d.profileMetadata(p), "\n"

end

######################################################################
__END__
% doi_data 10.1006/jmbi.2000.4282
>> Data types for doi:10.1006/jmbi.2000.4282:
profile
label
resource

>> Data values for doi:10.1006/jmbi.2000.4282:
doi:10.profile/crossref
Mech. Sys. Sig. Pro. 14, 6 (2000), 847 - Original Article
Mech. Sys. Sig. Pro. 14, 6 (2000), 847 - Corrigendum
http://www.idealibrary.com/links/doi/10.1006/jmbi.2000.4282
http://www.idealibrary.com/links/doi/10.1006/jmbi.2000.4440

>> Data groups for doi:10.1006/jmbi.2000.4282:
DataGroups (2) = [

profile => doi:10.profile/crossref
resource => http://www.idealibrary.com/links/doi/10.1006/jmbi.2000.4282
label => Mech. Sys. Sig. Pro. 14, 6 (2000), 847 - Original Article

profile => doi:10.profile/crossref
resource => http://www.idealibrary.com/links/doi/10.1006/jmbi.2000.4440
label => Mech. Sys. Sig. Pro. 14, 6 (2000), 847 - Corrigendum

]

>> Application profiles for doi:10.1006/jmbi.2000.4282:
doi:10.profile/crossref

>> Kernel metadata for doi:10.1006/jmbi.2000.4282:
<?xml version="1.0" encoding="UTF-8"?>
<!-- (C) 2001 International DOI Foundation -->
<!DOCTYPE kernel SYSTEM "doi_kernel_v0_1.dtd">
<kernel>
<doi>
<string>10.1006/jmbi.2000.4282</string>
<prefix>10.1006</prefix>
<suffix>jmbi.2000.4282</suffix>
</doi>
<entity type="abstraction">
<profile mode="visual" name="CrossRef">
<title></title>
<agent role="author">Jiang, Y.</agent>
</profile>
</entity>
</kernel>

>> Profile metadata for doi:10.1006/jmbi.2000.4282:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE doi_batch SYSTEM "doi_journal_article_v0_3.dtd">
<doi_batch version="0.3">
<head>
<doi_batch_id>XRef::Resolver_26-Mar-2001@5:21:26</doi_batch_id>
<timestamp>26-Mar-2001@5:21:26</timestamp>
<depositor>
<name></name>
<email_address></email_address>
</depositor>
<registrant></registrant>
</head>
<body>
<doi_record type="full_text">
<doi_data>
<doi>10.1006/jmbi.2000.4282</doi>
<url>http://dx.doi.org/10.1006/jmbi.2000.4282</url>
</doi_data>
<journal_article_metadata>
<article>
<author sequence="first">
<given_name>Y.</given_name>
<surname>Jiang</surname>
</author>
<date type="print">
<year>2001</year>
</date>
<date type="online">
<year>2001</year>
</date>
<enumeration>
<volume>305</volume>
<issue>3</issue>
<first_page>377</first_page>
</enumeration>
</article>
<journal>
<full_title>Journal of Molecular Biology</full_title>
<issn type="print">00222836</issn>
<issn type="electronic">10898638</issn>
</journal>
</journal_article_metadata>
</doi_record>
</body>
</doi_batch>
% cat doi_dataGroups
#!/export/home/tony/bin/ruby

require 'doi.rb'

d = DigitalObject.new(ARGV[0])
d.readDataStore

print "DOI: #{d.doi}\n\n"

######################################################################
#
# 1. Print a dump of the DOI Data Groups
#
######################################################################

d.dataGroupsDump

######################################################################
#
# 2. Add a new resource with profile "nu_crossref" and print dump
#
######################################################################

dg = DataGroup.new
dg.addData('resource', 'http://www.apple.com')
dg.addData('label', 'Apple')
dg.addData('detail', 'Apple - This is new resource #1')
d.addDataGroup(dg.getData, 'doi:10.profile/nu_crossref')

d.dataGroupsDump

######################################################################
#
# 3. Add a new resource with profile "crossref" and print dump
#
######################################################################

dg = DataGroup.new
dg.addData('resource', 'http://www.ibm.com')
dg.addData('label', 'Big Blue')
dg.addData('detail', 'IBM - This is new resource #2')
d.addDataGroup(dg.getData, 'doi:10.profile/crossref')

d.dataGroupsDump

######################################################################
#
# 4. Now print out the hyperlinked labels
#
######################################################################

print "DOI Application Profiles: #{d.profiles.join(', ')}\n\n"

print "And here are the hyperlinked labels:\n\n"

d.dataGroups.each do |dg|

 url = str = msg = nil
 dg.each do |aData|

   (type, data) = aData
   url = data if type =~ /resource/
   str = data if type =~ /label/
   msg = data if type =~ /detail/

 end
 next unless url
 str = url unless str
 msg = " onMouseOver=\"window.status='#{msg}';return true\"" if msg

 print "<a href=\'#{url}\'#{msg}>#{str}</a>\n"

end

######################################################################
__END__
% doi_dataGroups 10.1006/jmbi.2000.4282
DOI: 10.1006/jmbi.2000.4282

DataGroups (2) = [

profile = doi:10.profile/crossref
resource = http://www.idealibrary.com/links/doi/10.1006/jmbi.2000.4282
label = Mech. Sys. Sig. Pro. 14, 6 (2000), 847 - Original Article

profile = doi:10.profile/crossref
resource = http://www.idealibrary.com/links/doi/10.1006/jmbi.2000.4440
label = Mech. Sys. Sig. Pro. 14, 6 (2000), 847 - Corrigendum

]

DataGroups (3) = [

profile = doi:10.profile/crossref
resource = http://www.idealibrary.com/links/doi/10.1006/jmbi.2000.4282
label = Mech. Sys. Sig. Pro. 14, 6 (2000), 847 - Original Article

profile = doi:10.profile/crossref
resource = http://www.idealibrary.com/links/doi/10.1006/jmbi.2000.4440
label = Mech. Sys. Sig. Pro. 14, 6 (2000), 847 - Corrigendum

profile = doi:10.profile/nu_crossref
detail = Apple - This is new resource #1
label = Apple
resource = http://www.apple.com

]

DataGroups (4) = [

profile = doi:10.profile/crossref
resource = http://www.idealibrary.com/links/doi/10.1006/jmbi.2000.4282
label = Mech. Sys. Sig. Pro. 14, 6 (2000), 847 - Original Article

profile = doi:10.profile/crossref
resource = http://www.idealibrary.com/links/doi/10.1006/jmbi.2000.4440
label = Mech. Sys. Sig. Pro. 14, 6 (2000), 847 - Corrigendum

profile = doi:10.profile/nu_crossref
detail = Apple - This is new resource #1
label = Apple
resource = http://www.apple.com

profile = doi:10.profile/crossref
detail = IBM - This is new resource #2
label = Big Blue
resource = http://www.ibm.com

]

DOI Application Profiles: doi:10.profile/crossref,
doi:10.profile/nu_crossref

And here are the hyperlinked labels:

Mech. Sys. Sig. Pro. 14, 6 (2000), 847 - Original Article
Mech. Sys. Sig. Pro. 14, 6 (2000), 847 - Corrigendum
Apple
Big Blue
% doi_dataGroups ‘10.1016/S0304-4017(00)00375-7’
DOI: 10.1016/S0304-4017(00)00375-7

DataGroups (1) = [

profile = doi:10.profile/crossref
resource =
http://lookup.sciencedirect.com/doi.asp?publisherid=10.1016&doi=S03044017000
03757

]

DataGroups (2) = [

profile = doi:10.profile/crossref
resource =
http://lookup.sciencedirect.com/doi.asp?publisherid=10.1016&doi=S03044017000
03757

profile = doi:10.profile/nu_crossref
detail = Apple - This is new resource #1
label = Apple
resource = http://www.apple.com

]

DataGroups (3) = [

profile = doi:10.profile/crossref
resource =
http://lookup.sciencedirect.com/doi.asp?publisherid=10.1016&doi=S03044017000
03757

profile = doi:10.profile/nu_crossref
detail = Apple - This is new resource #1
label = Apple
resource = http://www.apple.com

profile = doi:10.profile/crossref
detail = IBM - This is new resource #2
label = Big Blue
resource = http://www.ibm.com

]

DOI Application Profiles: doi:10.profile/crossref,
doi:10.profile/nu_crossref

And here are the hyperlinked labels:

http://lookup.sciencedirect.com/doi.asp?publisherid=10.1016&doi=S03044017000
03757
Apple
Big Blue
ai.do
Application Interface for DigitalObjects – Reference

Class DataGroup < Object

Class Methods
new                                                                   DataGroup.new  dataGroup
 Returns a new dataGroup object.



Instance Methods
addData                                                  dataGroup.addData(type, data)  aHash
Adds a new data element to the dataGroup hash.

getData                                                  dataGroup.getData(type, data)  aHash
Returns the dataGroup hash.

readData                                             dataGroup.removeData(type, data)  aHash
Alias for getData method.

removeData                                      dataGroup.removeData(type, data)  aHash
Removes the data element from the dataGroup hash.




Class DigitalObject < Object

Class Methods
new                                                           DigitalObject.new(doi)  digitalObject
 Returns a new digitalObject object.



Pseudo-Class Methods (Class/Instance Shortcuts)
get                                                          DigitalObject.get(doi)  digitalObject
 Returns a new digitalObject object and populates it with DataGroups from the DataStore.
Equivalent to the following sequence:

d = DigitalObject.new(doi); digitalObject = d.readDataStore
Instance Methods – Accessing DataGroups
addDataGroup                                            digitalObject.addDataGroup(dg, profile) 
                                                                                    digitalObject
Add DataGroup dg with application profile profile to the digitalObject.

modifyDataGroup                                     digitalObject.modifyDataGroup(dg, profile) 
                                                                                   digitalObject
Modify DataGroup dg with application profile profile in the digitalObject.

removeDataGroup                                  digitalObject.removeDataGroup(dg, profile) 
                                                                                digitalObject
Remove DataGroup dg with application profile profile from the digitalObject.
Instance Methods – Accessing DataStore (Persistent Storage)
addDataStore                                                digitalObject.addDataStore(<dg>*) 
                                                                                    digitalObject
 Add DataGroups to the DataStore from the digitalObject. If DataGroups dg specified add to
those DataGroups.

createDataStore                                  digitalObject.createDataStore  digitalObject
 Create the DataStore and add DataGroups to the DataStore from the digitalObject.

deleteDataStore                                      digitalObject.deleteDataStore  digitalObject
 Delete the DataStore. (Issue: Deletion of “persistent” identifiers. Deprecated, or some general
handling mechanism?)

modifyDataStore                                        digitalObject.modifyDataStore(<dg>*) 
                                                                                    digitalObject
 Modify DataGroups within the DataStore with those from the digitalObject. If DataGroups dg
specified restrict modification to those DataGroups.

readDataStore                                           digitalObject.readDataStore(<dg>*) 
                                                                                 digitalObject
 Read DataGroups from the DataStore and add to the digitalObject. If DataGroups dg specified
restrict read to those DataGroups.

removeDataStore                                    digitalObject.removeDataStore(<dg>*) 
                                                                                 digitalObject
 Remove DataGroups from the DataStore. If DataGroups dg specified restrict remove to those
DataGroups.
Instance Methods – Data Element Accessors (Read-Only)
agents                                                           digitalObject.agents  anArray
 Returns anArray of the agent data elements contained in digitalObject.

aliases                                                           digitalObject.aliases  anArray
 Returns anArray of the alias data elements contained in digitalObject.

children                                                         digitalObject.children  anArray
 Returns anArray of the child data elements contained in digitalObject.

clients                                                            digitalObject.clients  anArray
 Returns anArray of the client data elements contained in digitalObject.

details                                                            digitalObject.details  anArray
 Returns anArray of the detail data elements contained in digitalObject.

genres                                                           digitalObject.genres  anArray
 Returns anArray of the genre data elements contained in digitalObject.

labels                                                             digitalObject.labels  anArray
 Returns anArray of the label data elements contained in digitalObject.

parents                                                          digitalObject.parents  anArray
 Returns anArray of the parent data elements contained in digitalObject.

profiles                                                           digitalObject.profiles  anArray
 Returns anArray of the profile data elements contained in digitalObject.

resources                                                     digitalObject.resources  anArray
 Return anArray of the resource data elements contained in digitalObject.

schemas                                                       digitalObject.schemas  anArray
 Returns anArray of the schema data elements contained in digitalObject.

services                                                         digitalObject.services  anArray
 Returns anArray of the service data elements contained in digitalObject.

types                                                              digitalObject.types  anArray
 Returns anArray of the type data elements contained in digitalObject.
Instance Methods – Data Element Tests
agent?                                            digitalObject.agent?(aString)  true or false
 Returns true if digitalObject has an agent data element aString.

alias?                                              digitalObject.alias?(aString)  true or false
 Returns true if digitalObject has an alias data element aString.

child?                                             digitalObject.child?(aString)  true or false
 Returns true if digitalObject has a child data element aString.

client?                                             digitalObject.client?(aString)  true or false
 Returns true if digitalObject has a client data element aString.

detail?                                             digitalObject.detail?(aString)  true or false
 Returns true if digitalObject has a detail data element aString.

genre?                                                  digitalObject.genre?(aString)  true or
                                                                                         false
 Returns true if digitalObject has a genre data element aString.

label?                                             digitalObject.label?( aString)  true or false
 Returns true if digitalObject has a label data element aString.

parent?                                                 digitalObject.parent?(aString)  true or
                                                                                          false
 Returns true if digitalObject has a parent data element aString.

profile?                                                 digitalObject.profile?(aString)  true or
                                                                                            false
 Returns true if digitalObject has a profile data element aString.

resource?                                             digitalObject.resource?(aString)  true or
                                                                                          false
 Returns true if digitalObject has a resource data element aString.

schema?                                              digitalObject.schema?(aString)  true or
                                                                                       false
 Returns true if digitalObject has a schema data element aString.

service?                                               digitalObject.service?(aString)  true or
                                                                                          false
 Returns true if digitalObject has a service data element aString.

type?                                              digitalObject.type?(aString)  true or false
 Returns true if digitalObject has a type data element aString.
Instance Methods – Metadata
kernelMetadata                                          digitalObject.kernelMetadata(profileDOI) 
                                                                                              aString
                                                              digitalObject.kernelMetadata aString
  Returns kernel metadata as aString from the application identified by profileDOI. If no profileDOI
is supplied returns kernel metadata from the first application found in the list of profiles.

profileMetadata                                         digitalObject.profileMetadata(profileDOI) 
                                                                                              aString
                                                              digitalObject.profileMetadata aString
  Returns profile metadata as aString from the application identified by profileDOI. If no profileDOI
is supplied returns kernel metadata from the first application found in the list of profiles.

				
DOCUMENT INFO
Shared By:
Categories:
Stats:
views:60
posted:3/18/2011
language:English
pages:17