Developer's Manual

Final version, 2002-11-04

Andras Micsik and Csaba Fulop

Developer's manual

The software consist of a client and a server. The client is a Swing application written in Java, the server is a set of CGI scripts written in Perl.

The Client

Architecture

The client is built on the Jena RDF toolkit [1]. The architecture of the client is shown on the figure. Java Swing provides the graphical presentation toolkit of the client. 'Drag and drop' metaphor is intensively used, mostly for the reuse of existing schema elements. All RDF (collected from the registry or created locally) are stored in memory according to the memory storage model of Jena. On request portions of this RDF can be saved in local files. The client communicates with the registry using the HTTP protocol, exchanging data in RDF format. As most of the transferred data is in RDF originally, this solution eliminates the need of data conversion during network transfer.

Figure One

Packages

The client consist of the following packages and classes:

Figure Two

net.rootdev.application package: it defines a document-window architecture to separate the document and application logic.
net.rootdev.meg package (later a name change will be necessary): the CORES client built on the previous application model.
net.rootdev.meg.model package: classes to build up a model. A document is menat here as a model of an RDF schema, and it is modelled in Java using these classes. The ModelItem class is the ancestor of all these classes.
net.rootdev.meg.view package: classes to build up a view, a window consist of this classes. The ModelView class is the ancestor of all these classes.

Back to the top

Classes

The major classes are:

MegDocument: the model of a schema.
MegWindow: the view of a schema.
AgencyDialog: input window for the details of an agency.
SearchMegWindow: search interface for the registry.
SubmissionDialog: interface for upload to the registry.
AnnotationDialog: annotate facility for the client.
REG: specific constants (namespaces, Jena variables).
Model: a class to store models
ModelItem: elements of a model. It's descendants are Agency, ApplicationProfile, Element, ElementSet, EncodingScheme, TermUsage and Value.
ModelView: a common interface for the elements of a view of a model. It's implementing classes are AgencyView, ApplicationProfileView, ElementView, ElementSetView, EncodingSchemeView, TermUsageView and ValueView.
TreeBrowser: A class to browse schemas. It's descendants are ApplicationProfilesBrowser, ElementSetsBrowser and EncodingSchemesBroser.

The Server

Architecture

The server is built on the Redland [2] RDF toolkit. The architecture of the server is shown on the figure. The server provides two interfaces: one for the user to browse its contents with a web browser, and a machine API for the client to upload schema definitions. Annotations can be created using both interfaces, but annotation display is available only through the web interface. The server is implemented as a set of Perl scripts, using the Redland Perl API to manipulate RDF databases. There are 3 separate databases for user registration data, annotations and the schema registry itself. The storage model used for these databases is Berkeley DB. Some other information are stored in files (e.g. session data, data for confirmation of registration), and the original RDF schemas are also available as plain files.

Figure Three

Back to the top

Modules

The server consist of the following modules and scripts: ,P.

Figure Four

The important functions are grouped in modules:

Registry.pm: functions responsible for display and handle the registry.
Annotation.pm: functions responsible for annotations.
Session.pm: session handling.
Users.pm: user management

Functions and scripts

The major functions are:

in Annotation.pm:

get_annotations_for: list the annotation database for annotations to the given resource.
get_annotation: get the details of a given annotation from the annotation database.
count_annotations: count the annotations for a given resource.
delete_annotation: delete a given annotation from the annotation database.
upload_annotation: upload a given annotation to the annotation database

Back to the top

in Registry.pm:

l: write debug information to the web servers error_log file.
start_html_page, start_annotation_page: headers for the web registry.
end_html_page, end_annotation_page: footers for the web registry.
class_label, class_label_from_uri: determine the class of a resource.
display_fields_for_class: the properties belong to the given resource class.
summary_fields_for_class: the properties to list when browsing.
concept_is_internal: it indicates if a property is internal and do not have to display.
uses_details_for_class, related_properties_for_class: links to associated resources for the given class.
nodes_sorted_by_name: sort the given resources by they name.
update_contents_index: update the index file (lindex.tab). lindex.tab is used for searching.
build_indexes: rebuild the registry database from the stored files.
name_for_resource: find the correct name property for a given resource and list it from the registry database.

in Session.pm:

getSession: get session data from the stored file or create it.
saveSession: save session data to file.

in Users.pm:

get_users_data: get the details of a given user for the annotation listing.
check_login: validate an attempt for login.

The scripts are:

add.pl: add a new annotation.
api.pl: api for the client. It can search, upload and annotate through this script.
browse.pl: browse the content of the registry.
confirm.pl: finish the new user registration process with confirmation.
list.pl: list the annotations for a given resource.
login.pl: handle and check the logins.
logout.pl: logout the current user.
new_user.pl: start the registration process for a new user and send her a confirmation code.

Back to the top

Work list: bug fixes, changes and developments

Server

- graphical layout changes (logo replaced, new header/footer etc.)
- provide download of the latest client
- the command='publish', class='element' parameter combination was not implemented
- evaluation of Java and Perl based solutions: functionality and performance tests
- installation and evaluation of W3C Annotea
- write simple perl client for annotea
- store annotations in Redland instead of Annotea (it was very slow)
- creation of annotation display window
- integration of annotation window with the registry browser
- support for deleting annotations
- editing annotations
- planning of user registration
- implementation of user registration in CORES registry
- planning and development of authentication
- login/logout page
- separating rdf databases for the registry, annotations and users
- change from the MEG namespace to CORES
- update the CORES RDFS (with annotations and users)
- making server installation easier
- switch to the CORES RDFS in the code
- display names instead of ids in registry browser
- numerous bug fixes: avoid drawing empty tables, correcting HTML output, etc.

Client

- implementation of annotation functionality in the client, new class AnnotationDialog to send annotations to the registry
- implementation of authentication for sending annotations
- modify the GridBagConstraints
- the MegDocument calls MegWindow.validate() for the necessary resizing after changing of the viewPane, to this the MegDocument needs a reference to MegWindow: MegDocument.mv
- modify the source of Document after 'save' or 'save as', so it remembers the (new) file
- there were some bug about the Element identifier
- change the MEG picture to CORES
- there were a bug in the upload: the client had used different namespace to identify the type of the Elements
- the program did not exit after closing of the last window, for this it needs a new method: MegWindow.windowClosing()
- closed windows were not removed from the window menu and they documents from the application, for this the client needs new method: Application.removeDocument()
- make checking for file opening, if the client can't open any files from the parameters then it opens an empty document
- the close menu did not do anything, to fix it the client needs a new method MegWindow.close() and MegWindow.closeWindow();
- correct removing and drawing of EncodingSchemes (there were a bug with JTree)
- add the missing schema elements (ElementSet-xmlNamespace, Element-datatype, Value-label, AppProfile-classification, ElementUsage-datatype)
- when removing a Value then remove all instance (if the EncodingScheme is associated with elements and element usages), this needs a new method: Value.removeItem:
- correct the drag&drop over label in TermUsage
- correct the SearchMegWindow: it had crashed after several searches (it had called bad function of the listeners of JTree with bad parameters)
- change in MegDocument.valueChanged() : the focus of the browser trees can change only by clicking on the title. (changing the focus by clicking in the tree is disturbing when drag&drop)
- change in MegDocument.remove() : maybe there isn't a selected element
- change method: ModelItem.removeItem: locate the removable elements by browser and PATH (if an EncodingScheme was associated with two element then both were removed)
- when removing from EncodingSchemesBrowser then remove all instance: new method was needed: EncodingScheme.removeItem()
- change in Document.saveAs: now it can overwrite existing files

References

[1] Jena RDF toolkit:
HTML: http://www.hpl.hp.com/semweb/index.html

[2] Redland RDF toolkit:
HTML: http://www.redland.opensource.ac.uk/

Back to the top

Web page by Rachel Heery of UKOLN.