Pawn:Package Design

Overview

PAWN allows 3rd-party package builders to be plugged in. While PAWN handles the file plan, category, and schedule organization, any data that it attaches to a category is generated through a package builder. A package builder is only concerned with generating items to attach under a category, and does not need to worry about any higher level organization, or other package categories. When building a package, the builder will be constrained by underlying policy attached to the category, and may query that policy to gain information on required elements and prohibited actions.

Builder Design

The package builder consists of two parts, an interface that can be registered and physical creation layer. Ideally, the creation layer and interface will both be pluggable, and allow different physical package implementations, imtermediate policy layers, and varying creation interfaces. However, in the interest of time, the low-level package and policy layer will NOT be pluggable in this release.

Interface builders in PAWN construct a package that is a hierarchy of typed bundles. This is merely an abstraction of linked METS documents. Bundles contain a name, interface-defined type, and optionally metadata, data, and other bundles. PAWN will take the bundles that a builder constructs and create low-level mets documents. Builders will use the Bundle interface to construct the package layout. During package construction, PAWN may prevent certain actions on the bundle depending on the underlying policy. Please see the [[PawnPolicy][PAWN policy]] documentation on how policy is implemented, and how an interface may query the policy for allowed/disallowed actions.

The base package in PAWN consists of metadata, data, minimal descriptive elements (Name), and child-packages. In Pawn, interfaces create packages that are filed under categories. Categories are defined in a particular domain's record schedule and are grouped together under arbitrary file plans. Internally, the file-plan can be thought of as a root package and categories are merely pointers to a sub-package. This internal package is NOT accessable to builders.

Registering new interfaces

The BuilderCreator class contains static methods for managing a set of available builder interfaces. Builder interfaces are classes that implement the BuilderInterface. The client, or extensions of it, are able to manually load builder classes by calling registerBuilder(name, class). This will make the builder globally available to the client's package builder. The Creator is also able so load interfaces from a properties file through loadBuilders.

A list of internal builders is located in the Resources/builder.properties file. For now, new builders should be listed in that file. At startup, the client will detect which builders are available on the classpath and register them appropriately

Sample builder.properties file:

#Should unavailable classes be flagged
ignore.unavailable=true

# register builder with class: 'edu.umiacs.pawn.builder2.DefaultBuilder' named: 'Default'
name.edu.umiacs.pawn.builder2.DefaultBuilder=Default

# sample unavailable class
name.edu.umiacs.pawn.bb=test

Creating new builder interfaces

New interfaces or builders that want to be used in PAWN must implement the BuilderInterface and must have a constructor that takes no arguments. While not restricted, the builder should not popup any gui elements, or assume that it should start building a package until getPanel is called. It should also be noted that PAWN will not re-use builder instances for creating new packages.

Builders are named with a URN identifying them. This URN is used to tag the creator of a given bundle. PAWN then uses these tags to match pre-existing bundles or packages with the builder that created it. A list of [[Pawn:Builder Urns][Builder URNs]] is available.

A common way to create a new builder interface in netbeans is to create a new JPanel form, and have it implement the BuilderInterface.

Methods to implement:

• getPanel(Bundle, <nop>InterfaceHandler) , return new JPanel that will be embedded in a builder dialog window. The returned panel should not implement finish or close buttons as the hosting dialog will supply those.
  • Bundle - A bundle that will be attached to the category
• getBuilderURN()

public class DefaultBuilder extends javax.swing.JPanel implements BuilderInterface {
    
    private Bundle bundle = null;
    
    public DefaultBuilder() {
        initComponents();
        
    }

    public javax.swing.JPanel getPanel(Bundle bundle, InterfaceHandler handler) {
        updateBundle(bundle);
        // register finish and close methods into the handler
        return this;
    }

    /**
     * change to your own descriptor
     */
    public String getBuilderURN() {
        return "urn:pawn:builder:default";
    }
...
...

Modifying Content

An interface is responsible for creating a package of data that pawn attaches to a category. The interface does this using the Bundle object that is passed into it. This bundle combined with the Policy that was attached allows the interface to create legal packages. Each category will have only one bundle attached to it.

The bundle object is a simple object that contains a name, type, ordered data, metadata, and other bundles. Through the nesting of bundles a hiearchy from the root bundle is creates. Bundles can be moved to create other bundles.

Bundles are associated with the interface that created them, however as bundles will be ingested and and reloaded by clients, any interface should be prepared to handle bundles created by another interface (even if to preserve their stucture and make them immutable). Interfaces should try not to change the type of items unless they change their namespace as well.(IE, if you're a geospatial interface, it would be bad practice to change items developed by a book interface)

Bundle

namespace

Namespace that this bundle belongs to. This is the URN of the creating interface. Interfaces should check this along with type to make sure it was the original author of a bundle.

type

Client defined type of the bundle (ie, cd, directory, page, chapter, etc...)

name

Descriptive name of the bundle (ie, 'My Documents', 'page 1', etc...)

Data

An ordered set of data objects that belongs to this bundle.

Metadata

An ordered set of #metadata objects that are assigned to this bundle.

Bundles

An ordered set of bundles that are children of this bundle.

Data Objects

Name

Descriptive name for this metadata

Type

Usage or type of this metadata. May be null.

File

Physical file (java.io.File) to include.

Metadata

An ordered set of metadata objects that are assigned to this file.

Metadata objects

Name

Type

Descriptive usage of type for this file. This is NOT mime type. May be null. This should be used by the interface to determine how to best display this metadata.

File

inputstream or file for this metadata