draft-ietf-acap-dataset-model-00.txt   draft-ietf-acap-dataset-model-01.txt 
Network Working Group Ryan Troll Network Working Group Ryan Troll
Document: draft-ietf-acap-dataset-model-00.txt Carnegie Mellon Document: draft-ietf-acap-dataset-model-01.txt Carnegie Mellon
Expires August 21, 1999 February 16, 1999 Expires October 3, 1999 March 29, 1999
An Introduction to the ACAP Dataset Model An Introduction to the ACAP Dataset Model
<draft-ietf-acap-dataset-model-00.txt> <draft-ietf-acap-dataset-model-01.txt>
Status of this Memo Status of this Memo
This document is an Internet-Draft and is in full conformance with This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026. Internet-Drafts are all provisions of Section 10 of RFC2026. Internet-Drafts are
working documents of the Internet Engineering Task Force (IETF), its working documents of the Internet Engineering Task Force (IETF), its
areas, and its working groups. Note that other groups may also areas, and its working groups. Note that other groups may also
distribute working documents as Internet-Drafts. distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six Internet-Drafts are draft documents valid for a maximum of six
skipping to change at page 1, line 41 skipping to change at page 1, line 41
The ACAP [ACAP] Dataset Model is very extensible, and allows The ACAP [ACAP] Dataset Model is very extensible, and allows
applications to easily share options and information. With this applications to easily share options and information. With this
extensibility comes a complexity that an application designer must extensibility comes a complexity that an application designer must
fully understand in order to interoperate while using ACAP. fully understand in order to interoperate while using ACAP.
This document will help the reader understand and visualize the ACAP This document will help the reader understand and visualize the ACAP
hierarchy, come to a better understanding of how to design and hierarchy, come to a better understanding of how to design and
access ACAP datasets, and understand the relationship between access ACAP datasets, and understand the relationship between
attributes, entries, datasets, and dataset classes. attributes, entries, datasets, and dataset classes.
0. Outstanding Issues
Need to address inheritance. It is ignored in this document, and is
a big hairy beast that should be discussed. However, I need help
doing so, as I don't fully understand when it should and should not
be used yet.
1. Introduction 1. Introduction
The Application Configuration Access Protocol [ACAP] is designed to The Application Configuration Access Protocol [ACAP] is designed to
support remote storage and access of program option, configuration, support remote storage and access of program option, configuration,
and preference information. The data store model is designed to and preference information. The data store model is designed to
allow a client relatively simple access to data, to allow new allow a client relatively simple access to data, to allow new
information to be easily added without server reconfiguration, and information to be easily added without server reconfiguration, and
to promote the use of both standardized data and custom or to promote the use of both standardized data and custom or
proprietary data. proprietary data.
skipping to change at page 2, line 28 skipping to change at page 2, line 38
Dataset Class A dataset class is a formal description of how to use Dataset Class A dataset class is a formal description of how to use
information stored within a dataset. Descriptions of information stored within a dataset. Descriptions of
all attributes, and what their values mean, make up a all attributes, and what their values mean, make up a
dataset class. dataset class.
Dataset Every level of the ACAP hierarchy is a dataset. Dataset Every level of the ACAP hierarchy is a dataset.
Datasets contain entries, and/or other datasets. Datasets contain entries, and/or other datasets.
Datasets may inherit entries from other datasets, or Datasets may inherit entries from other datasets, or
be standalone repositories of information. be standalone repositories of information.
Sub-Dataset A dataset may contain pointers to other datasets. Sub-Dataset A dataset may contain other datasets. These datasets
These datasets are subsets of the main dataset, and are subsets of the main dataset, and may contain
may contain entries that are grouped together for a entries that are grouped together for a common
common reason. In a dictionary, words are grouped reason. In a dictionary, words are grouped together
together based on their first letter. These smaller based on their first letter. These smaller groupings
groupings are subsets of the entire dictionary, just are subsets of the entire dictionary, just like sub-
like sub-datasets are subsets of the entire dataset. datasets are subsets of the entire dataset.
Sub-datasets do not have to reside on the same ACAP Sub-datasets do not have to reside on the same ACAP
server as the dataset containing the sub-dataset server as the dataset containing the sub-dataset
pointer. A site may provide an ACAP server for all pointer. A site may provide an ACAP server for all
users, and this ACAP server may contain custom users, and this ACAP server may contain custom
bookmarks for all users. If a user decides to use bookmarks for all users. If a user decides to use
another ACAP server for his/her ACAP needs, one entry another ACAP server for his/her ACAP needs, one entry
in the users bookmark dataset could be a sub-dataset in the user's bookmark dataset could be a sub-dataset
pointer back to the site-wide dataset. pointer back to the site-wide dataset.
A full dataset may also be a sub-dataset of another A full dataset may also be a sub-dataset of another
dataset. Being a sub-dataset does not change how the dataset. Being a sub-dataset does not change how the
dataset is accessed or viewed. Sub-datasets provide dataset is accessed or viewed. Sub-datasets provide
a way for a dataset to break up its data into smaller a way for a dataset to break up its data into smaller
chunks, and/or share data between datasets. chunks, and/or share data between datasets.
Entry One item in a dataset is an entry (IE: A web Entry One item in a dataset is an entry (e.g. A web
bookmark). bookmark). An entry consists of a collection of
An entry consists of a collection of attributes. attributes.
Attribute The smallest piece of information in an ACAP dataset. Attribute The smallest piece of information in an ACAP dataset.
An attribute describes one aspect of an entry, and An attribute describes one aspect of an entry, and
consist of a name and a value. (IE: the name 'color' consist of a few pieces of meta-data. The most
and the value 'black') important meta-data is the name and a value. (e.g.
the name 'color' and the value 'black')
2. ACAP Data Model 2. ACAP Data Model
This section defines all of the parts of the ACAP data model, This section defines all of the parts of the ACAP data model,
starting with the smallest piece of information. starting with the smallest piece of information.
2.1. Attribute / Value 2.1. Attribute / Value
The smallest piece of information in the ACAP data store is an The smallest piece of information in the ACAP data store is an
attribute. An attribute contains two pieces of information: a name, attribute. An attribute includes two pieces of information: a name,
and a value. Attributes may also have multiple values. Multiple and a value. Attributes may also have multiple values. Multiple
values are stored as parenthesized lists of values. The value types values are stored as parenthesized lists of values. The value types
Atom, Number, String, Parenthesized List, and NIL are defined in Atom, Number, String, Parenthesized List, and NIL are defined in
[ACAP], section 2.6. [ACAP], section 2.6.
Some attributes are already defined, and are used for every entry. Some attributes are already defined, and are used for every entry.
These attributes include "entry", which is the name of the entry, These attributes include "entry", which is the name of the entry,
and "subdataset", which is used to indicate that the entry and "subdataset", which is used to indicate that the entry
represents a sub-dataset. represents a sub-dataset. These attributes are not necessarily
shown to the user.
The bookmark dataset [BOOK] includes the attributes The bookmark dataset [BOOK] includes the attributes
"bookmarks.Description", containing a user-assigned description "bookmarks.Description", containing a user-assigned description
("CMU's ACAP Page"); "bookmarks.Name", containing the name of the (e.g. "CMU's ACAP Page"); "bookmarks.Name", containing the name of
reference ("ACAP Home Page"); and "bookmarks.URL", which is the the reference (e.g. "ACAP Home Page"); and "bookmarks.URL", which is
bookmarked URL ("http://asg.web.cmu.edu/acap"). These attributes, the bookmarked URL (e.g. "http://asg.web.cmu.edu/acap"). In this
along with others, will allow clients to use and/or present the dataset, the attribute "entry" is not shown to the user, and is only
bookmarks to the user. used as a uniquifier within the dataset itself. These attributes,
along with others, contain all the information needed by a client
regarding this bookmark.
The dictionary dataset [DICT] includes the attributes "entry" and The dictionary dataset [DICT] includes the attributes "entry" and
"dictionary.definition". The attribute "entry" may have the value "dictionary.definition". The attribute "entry" may have the value
"spam", while the attribute "dictionary.definition" may have the "spam", and is shown to the user, while the attribute
value "("To send multiple unsolicited messages" "A meat-like "dictionary.definition" may have the value "("To send multiple
substance")". unsolicited messages" "A meat-like substance")".
2.1.1. Attribute Naming Scheme 2.1.1. Attribute Naming Scheme
Attributes MUST adhere to a strict naming scheme. Attributes names Attributes MUST adhere to a strict naming scheme. Attributes names
which do not contain a dot (".") are reserved for standardized which do not contain a dot (".") are reserved for standardized
attributes which have meaning in any dataset. ("entry" and attributes which have meaning in any dataset. ("entry" and
"modtime", for example.) All other attributes MUST have a name of "modtime", for example.) All other attributes MUST contain a dot
the format "Dataset.Attr", where 'Dataset' is the name of the ("."), and by convention use a name of the format "Dataset.Attr",
dataset, and 'Attr' is the name of the attribute within the dataset. where 'Dataset' is the name of the dataset, and 'Attr' is the name
('Attr' may contain dots.) of the attribute within the dataset. ('Attr' may contain dots.)
Some attributes are pre-defined, and have special meanings. These Some attributes are pre-defined, and have special meanings. These
attributes are: attributes are:
entry The name of the entry within the dataset. entry The name of the entry within the dataset. This value
MUST be unique within the dataset.
modtime Timestamp of the last modification to anything within modtime Timestamp of the last modification to anything within
this entry. this entry. This is generated by the server.
subdataset If set, this attributes indicates the existence of a subdataset If set, this attributes indicates the existence of a
sub-dataset of this entry. sub-dataset of this entry.
For more information on the predefined attributes, consult [ACAP], For more information on the predefined attributes, consult [ACAP],
section 3.1.1. section 3.1.1.
Attribute names are unique across all datasets. This is Attribute names are unique across all datasets. This is
accomplished by the attribute naming scheme: all attribute names accomplished by the attribute naming scheme: all attribute names
MUST be of the form "<dataset class>.<attribute-name>". MUST be of the form "<dataset class>.<attribute-name>".
skipping to change at page 5, line 13 skipping to change at page 5, line 27
standard way to choose an entry name. standard way to choose an entry name.
For example, when using ACAP to store a personal dictionary, the For example, when using ACAP to store a personal dictionary, the
entry name may be the word. Since the word may have multiple entry name may be the word. Since the word may have multiple
definitions, the dictionary dataset has been structured to use definitions, the dictionary dataset has been structured to use
multi-valued attributes to allow clients to store multiple multi-valued attributes to allow clients to store multiple
definitions. definitions.
On the other hand, an ACAP entry describing a bookmark may contain On the other hand, an ACAP entry describing a bookmark may contain
the URL, name, type, and last visited time. The name of the the URL, name, type, and last visited time. The name of the
bookmark entry may be a numeric uniquifier, which has no meaning to bookmark entry may be an alpha-numeric uniquifier, which has no
the rest of the entry. meaning to the rest of the entry.
Another example is to compare the ACAP data store to a filesystem. Another example is to compare the ACAP data store to a filesystem.
In this case, every entry may be considered a directory entry. The In this case, every entry may be considered a directory entry. The
contents of the files are irrelevant, and only the file attributes contents of the files are irrelevant, and only the file attributes
are examined. The name of the file is unique within the dataset, are examined. The name of the file is unique within the dataset,
just like the dataset entry names, and all entries within the just like the dataset entry names, and all entries within the
directory have an owner, a modification time, a last accessed time, directory have an owner, a modification time, a last accessed time,
and a size. and a size.
2.3. Dataset 2.3. Dataset
A dataset is a collection of entries and datasets, which represent a A dataset is a collection of entries and datasets, which represent a
set of the information being defined. When looking at a collection set of the information being defined. When looking at a collection
of bookmarks, a dataset may be defined for each of your folders of of bookmarks, a dataset may be defined for each of your folders of
bookmarks, with a fifth dataset containing all of these folders, as bookmarks, with a top-level dataset containing all of these folders,
well as any unfiled bookmarks. as well as any unfiled bookmarks.
2.3.1. Dataset Inheritance 2.3.1. Dataset Inheritance
Datasets may also inherit values from other datasets. Sites may Datasets may also inherit values from other datasets. Sites may
want to define a base set of bookmarks that all of their users see. want to define a base set of bookmarks that all of their users see.
This can be accomplished by using dataset inheritance. When This can be accomplished by using dataset inheritance. When
accessing a dataset that inherits from another, the accessed dataset accessing a dataset that inherits from another, the accessed dataset
appears to contain everything that is actually stored in it, as well appears to contain everything that is actually stored in it, as well
as what is stored in the dataset it is inheriting from. as what is stored in the dataset it is inheriting from.
skipping to change at page 6, line 8 skipping to change at page 6, line 23
One important thing to remember: a client can not distinguish One important thing to remember: a client can not distinguish
between inherited entries, and entries that are actually in the between inherited entries, and entries that are actually in the
dataset, unless the search that is performed specificly says not to dataset, unless the search that is performed specificly says not to
use inheritance. Designers and adminstrators MUST be careful when use inheritance. Designers and adminstrators MUST be careful when
using inheritance. using inheritance.
2.4. Dataset Class 2.4. Dataset Class
A dataset class is a formal definition of a dataset. The class A dataset class is a formal definition of a dataset. The class
definition describes what data will be stored, where the information definition describes what data is stored, where the information is
will be stored, and what format it will be stored in. This allows stored, and what format it is stored in. This allows multiple
multiple applications to use the same data within the ACAP server, applications to use the same data within the ACAP server, without
without having to worry about breaking it for other applications. having to worry about breaking it for other applications. As long
As long as all applications adhere to the dataset class definition, as all applications adhere to the dataset class definition, there
there will be no problems. will be no problems.
Standardizing dataset class definitions allows multiple applications Standardizing dataset class definitions allows multiple applications
to share data, even if they are from different vendors. By defining to share data, even if they are from different vendors. By defining
a common bookmark dataset class, all web browsers would be able to a common bookmark dataset class, all web browsers are able to share
share their bookmarks with one another. In addition, by storing their bookmarks with one another. In addition, by storing their
their bookmarks on an ACAP server, multiple instantiations of bookmarks on an ACAP server, multiple instantiations of browsers
browsers across multiple computers and operating systems would be across multiple computers and operating systems are able to safely
able to safely modify and update the list, with all other apps modify and update the list, with all other apps picking up the
picking up the changes as they are made. changes as they are made.
2.4.1. Dataset Class Naming Scheme 2.4.1. Dataset Class Naming Scheme
All dataset classes have a name. The name is used to locate the All dataset classes have a name. The name is used to locate the
dataset class within the hierarchy. Dataset class names MUST either dataset class within the hierarchy. Dataset class names MUST either
be of the form "vendor.<vendor/product>", or be specified in a be of the form "vendor.<vendor/product>", or be specified in a
standards track or IESG approved experimental RFC. The proposed standards track or IESG approved experimental RFC. The proposed
dictionary dataset class will use the dataset class name dictionary dataset class uses the dataset class name "/dictionary",
"/dictionary", while a vendor's mechanism for storing application- while a vendor's mechanism for storing application-specific options
specific options (such as window location) may be under (such as window location) may be under, for example,
"/cyrusoft.mulberry". "/vendor.cyrusoft.mulberry".
3. Hierarchy 3. Hierarchy
The dataset namespace is a slash-separated hierarchy. The first The dataset namespace is a slash-separated hierarchy. The first
part of the namespace is the dataset class. For standard datasets, part of the namespace is the dataset class. For standard datasets,
this will be the name specified by the standard, such as this will be the name specified by the standard, such as
"/bookmarks" or "/dictionary". For vendor-specific dataset classes, "/bookmarks" or "/dictionary". For vendor-specific dataset classes,
this will be the name of the vendor and the product, separated by a this will be the prefix "vendor", the name of the vendor, and the
period. (IE: "/cyrusoft.mulberry") product, all separated by a periods. (e.g.
"/vendor.cyrusoft.mulberry")
The second part of the namespace is the scope of the dataset to be The second part of the namespace is the ownership class, or scope of
looked up. This can be "site", for server-wide datasets; "group" the dataset. This can be "site", for server-wide datasets; "group"
for administrative group datasets; "host" for host specific data; or for administrative group datasets; "host" for host specific data; or
"user" for a user's data. "user" for a user's data.
If the scope is "group", "host", or "user", the third part of the If the scope is "group", "host", or "user", the third part of the
namespace identifier is the name of the group, host, or user being namespace identifier is the name of the group, host, or user. (For
looked up. (For example, example, "/vendor.cyrusoft.mulberry/host/lister.net.cmu.edu" would
"/cyrusoft.mulberry/host/lister.net.cmu.edu" would be Mulberry be Mulberry preferences specific to the host "lister.net.cmu.edu".)
preferences specific to the host "lister.net.cmu.edu".)
To fetch the bookmarks for user "ryan" on the ACAP server, the To fetch the bookmarks for user "ryan" on the ACAP server, the
dataset to be searched would be "/bookmarks/user/ryan". If "ryan" dataset to be searched would be "/bookmarks/user/ryan". If "ryan"
is the current ACAP user, this may be abbreviated as "/bookmarks/~". is the current ACAP user, this may be abbreviated as "/bookmarks/~".
The dataset "/byowner" is reserved, and allows searches to show what The dataset "/byowner" is reserved, and allows searches to show what
dataset classes are owned by a given user. Searching dataset classes are owned by a given user. Searching
"/byowner/user/ryan" will show all of the dataset classes in use by "/byowner/user/ryan" will show all of the dataset classes in use by
user "ryan". user "ryan".
skipping to change at page 8, line 20 skipping to change at page 8, line 25
entry 12dag8 entry 12dag8
bookmarks.Name "SSH (Secure Shell) Home Page" bookmarks.Name "SSH (Secure Shell) Home Page"
bookmarks.Description "" bookmarks.Description ""
bookmarks.URL "http://www.cs.hut.fi/ssh/" bookmarks.URL "http://www.cs.hut.fi/ssh/"
bookmarks.Type "link" bookmarks.Type "link"
entry 13ksjhdfgpoa entry 13ksjhdfgpoa
bookmarks.Type "separator" bookmarks.Type "separator"
entry 14roblink entry 14roblink
subdataset "//other.acap.domain//bookmarks/rob/public" subdataset "acap://other.acap.domain/bookmarks/rob/public"
bookmarks.Name "Rob's Public Bookmarks" bookmarks.Name "Rob's Public Bookmarks"
bookmarks.Type "folder" bookmarks.Type "folder"
entry 15emailfoo entry 15emailfoo
subdataset . subdataset .
bookmarks.Name "Email Stuff" bookmarks.Name "Email Stuff"
bookmarks.Type "folder" bookmarks.Type "folder"
In dataset /bookmarks/user/ryan/email-stuff In dataset /bookmarks/user/ryan/Email Stuff
entry 2baz212 entry 2baz212
bookmarks.Name "ACAP Home Page" bookmarks.Name "ACAP Home Page"
bookmarks.Description "It's not LDAP" bookmarks.Description "It's not LDAP"
bookmarks.URL "http://asg.web.cmu.edu/acap" bookmarks.URL "http://asg.web.cmu.edu/acap"
bookmarks.Type "link" bookmarks.Type "link"
entry 3bar51 entry 3bar51
bookmarks.Name "IMAP Home Page" bookmarks.Name "IMAP Home Page"
bookmarks.Description "Protocol for fetching messages" bookmarks.Description "Protocol for fetching messages"
bookmarks.URL "http://asg.web.cmu.edu/cyrus" bookmarks.URL "http://asg.web.cmu.edu/cyrus"
bookmarks.Type "link" bookmarks.Type "link"
entry 812foo entry 812foo
bookmarks.Name "Sieve Home Page" bookmarks.Name "Sieve Home Page"
bookmarks.Description "Sieve mail filtering language" bookmarks.Description "Sieve mail filtering language"
bookmarks.URL "http://asg.web.cmu.edu/sieve" bookmarks.URL "http://asg.web.cmu.edu/sieve"
bookmarks.Type "link" bookmarks.Type "link"
4.1.2. Generated Bookmarks File 4.1.2. Generated Bookmarks File
Based on this information, the following web bookmark file can be Based on this information, the following web bookmark display can be
generated: generated:
Lurkers Guide to Babylon 5 Lurkers Guide to Babylon 5
SSH (Secure Shell) Home Page SSH (Secure Shell) Home Page
---------------------------- ----------------------------
Rob's Public Bookmarks -> Rob's Public Bookmarks ->
Email Stuff -> Email Stuff ->
And, the "Email Stuff" folder / sub-menu would contain: And, the "Email Stuff" folder / sub-menu would contain:
 End of changes. 25 change blocks. 
64 lines changed or deleted 75 lines changed or added

This html diff was produced by rfcdiff 1.34. The latest version is available from http://tools.ietf.org/tools/rfcdiff/