See the Overview for the current architecture and usage hints. Please also see the Javadocs.

Implementation

This section is partly out of date.

Unique TextGridObjects

TextGridObjects are unique, i.e. there is never more than one TextGridObject per referable object in TextGrid.

TextGridObject does not have a public constructor. The preferred mode of getting one is to adapt an existing representation of the object to TextGridObject.class. Alternatively, you may call one of the factory functions TextGridObject.create, which take either an URI or a metadata block.

Object interaction (implementation issue)

Modifying Metadata

Modifying Metadata works as follows:

  1. Obtain a TextGridObject
  2. Register a modification listener with the TextGridObject.
  3. Fill your UI with the information from the TextGridObject.
  4. If the listener fires, you should update your local fields.
  5. If your local fields change, you should update the TextGridObject

Saving metadata

Metadata and their corresponding objects are tightly coupled. If you (re-)load an object's contents (e.g. IFile.getContents()), the metadata is (re-)loaded from the Grid. If you save an object to the grid, its metadata will be saved, as well; and the TextGridObject will be updated with the metadata from the grid). Additionally, it is possible to save only the metadata.

Creating an object

When objects are created, the following phases are possible:

  1. The object is created, and it's metadata is still incomplete.
  2. The object is first stored to the grid (→ TGcrud#create)
  3. The object is updated later

Preliminary object creation

When the object's metadata is not yet complete or the object has not been stored to the grid for some other reason, it does not have its final textgrid: URI. Instead, the object is assigned a temporary URI by calling TextGridObject#create(OMElement) or TextGridObject#create(). This temporary URI has the form textgrid-temp:42.

Saving the object (TGcrud#create)

When you first save the object (either by calling ITextGridObject.saveMetadata() or IFile.setContents(...)) we need the additional metadata provided. If it is, TGcrud#create is called with the metadata and (optionally) the data.

TGcrud#create returns with a new URI from the textgrid: scheme. The TextGridObject stays the same, the IFile's link is modified. Clients addressing the TextGridObject with the “old” URI (from textgrid-temp:) will still receive the TextGridObject, nut the latter's getURI() method will return the new URI (this works by adding a link from the new URI to the registry instead of replacing the temporary URI).

Editors and Save as …

The API for saving files leaves the Save as … functionality basically to the individual editors: There are methods ISaveablePart#doSave(IProgressMonitor) and ISaveablePart#doSaveAs(). doSave saves the IEditorInput, ie it usually calls IFile#setContents, which will result in an IFileStore#openOutputStream and consecutive save operations. With doSaveAs, it's up to the editor to invoke a »Save as …« dialog.

If it is not possible to hijack the general save-as dialog, I suggest that we implement the save as functionality separately, controlled from the EFS layer. I.e., the EFS layer pops up a dialog asking for the new metadata:

File → Save to new TextGridObject …
  TextGridObject(activeEditor.getEditorInput).saveAs := true
  activeEditor.doSave()
            

This will finally result in a call to TGFileStore.openOutputStream(), in which:

    if TextGridObject(this).saveAs then
      newMetadata := showMetadataWizard(TextGridObject(this), NEW_VERSION)
      TGcrud.create(newMetadata, this)
            

Now we must tell the EditorPart that it is working with a different object now, since it wouldn't expect that. Options are:

Changing the link.
We simply change the IFile by setting it to a different link (using createLink(newURI)). Maybe we also have to fire a “resource changed” event or something like that. Disadvantage: This is not intuitive, because the user then works with a different file, but not with a different file representation in the GUI.
Reopening the editor.
We close the calling editor and open it anew, with the new object's new IFile. Disadvantage: Closing and reopening the editor is probably neither what the user nor what the editor expect. Additionally, we lose the editor's state as far as it is not stored with the object (cursor position etc.)
A specialized interface.
Does only work with our editors, not with others'.