| <= Previous | Next => | Table of Contents | TwICE User's Manual |
This section needs a lot of work.
TwICE is made up of three layers: the core, demo-specific subscription services, and the user interface.
At its core, any ICE implementation must speak HTTP, parse and output XML, and handle ICE data types like timestamps, URLs, payloads, and identifiers. In addition, it makes sense to provide behavior common to syndicators and subscribers. ICE 2.0 implementations must also support SOAP.
TwICE is no different. It uses Java classes to speak HTTP and retrieve URL contents. Earlier versions rely upon MinML2 to parse well-formed XML and some DOM classes to write XML. By default, TwICE 2.0 uses the XML parser provided with the Java 2 Runtime Environment. TwICE provides timestamp parsing and formatting. Finally, the TwICE core contains classes that can build ICE messages and that implement common syndicator and subscriber behavior.
Java's networking classes provide ICE payload transport and content retrieval. For convenience, SOAP transport functionality can be easily implemented using a SOAP engine. TwICE 2.0 uses Apache Axis.
By default, TwICE 2.0 is configured to use XML parsing as provided with the Java 2 Runtime Enviroment (version 1.4 or higher). TwICE 1.x used the MinML2 parser and some custom classes as described below.
The MinML2 parser by John Wilson provides XML parsing. The jimm.twice.xml.dom package contains a simple set of classes for creating DOM objects that can write themselves as XML. The abstract class jimm.twice.ice.PayloadParser is a subclass of MinML2; it reads and stores tags and attributes common to all ICE payloads. Concrete subclasses RequestParser and ResponseParser store information unique to ICE requests and responses.
A hierarchy of classes in the package jimm.twice.ice.payload are useful for building common ICE payloads. Each has a toString method that returns the payload as XML. Not every possible ICE payload has its own class.
The package jimm.twice.xml.dom contains a set of classes that provide a DOM-type way of building XML documents. This is not a real DOM implementation. For example, the Doctype class does not support entities, the XMLDecl class does not support the encoding or standalone attributes, and the Document class does not allow a epilogue (miscellaneous tags after the close of the root node).
To include a file in your XML, use the InlineFile class. It never loads the whole file in memory, and it encodes the file as base64 by default.
Call Document.toString to retrieve the XML string or Document.writeTo to write the XML string to a java.io.Writer. The latter method avoids building the strings in memory, which is especially useful when you are building a large XML document containing data such as inline file contents.
The decidedly non-DOM class InlineFile is a kind of text element that holds a File. It never loads the contents of the file in memory, but streams the contents to a java.io.Writer from the file on disk instead. By default, an inline file is base64 encoded.
Internally, all time stamps are stored as java.util.Date instances. The DateTime class contains static methods that use instances of java.text.SimpleDateFormat to create the strings ICE requires for dates and times.
TwICE does not yet generate or parse ICE time durations or date ranges.
The state common to syndicators and subscribers is stored in instances of Party. The behavior common to both lives in a class called ICEMachine. This class provides pinging, sending requests, and returning "normal" and error repsonses.
Information about subscriptions is held in instances of Subscription.
Error codes and I18N.
Logging.
The package jimm.twice.ice.identifier contains classes useful for generating identifiers. These identifiers are not UUIDs. To generate a new UUID under Unix, try the uuidgen command.
Ping, time, date, error. Both push and pull. The string describing the state of a date subscription is the date string itself.
Content may be delivered inline or by reference; inline = ice-item, by reference = ice-ref.
The subscriber stores the contents of subscriptions inside the directory
named by the property "subscriber.subscription_contents_dir". Each
subscription has its own subdirectory under that directory. If we have a
content-filename attribute, the contents are place in a subdirectory of
that subscription directory with the given file name.
content-filename is a string containing a relative path to the
file, for example "foo/bar/bletch.txt". Given that content-filename, the
contens of that file will be stored in
subscriber.subscription_contents_dir/subId/foo/bar/bletch.txt.
If we have no content-filename attribute, the contents are
stored in a file whose name is subId. This means that the final
destination is
subscriber.subscription_contents_dir/subId/subId.
Syn. and sub. "mini-sites": Web pages using JSP.
Listener dispatches requests.
Mini-sites: Interface plus role-specific behavior. Much behavior has been factored out of mini-sites. What's left is specific to the persistence mechanism, properties file, and Servlet API.
A syndicator...
A subscriber...
TwICE is useful even without Tomcat, the JSP pages, or the TwICESyndicator and TwICESubscriber classes. The other packages (jimm.twice.ice, jimm.twice.ice.payload, jimm.twice.ice.identifier, jimm.twice.xml.dom, and jimm.twice.util) stand on their own. The only other thing you need is a way to send and receive ICE payloads. The ICE specification does not require the use of HTTP; that's just the most commonly used protocol.
The directory tests contains JUnit tests. The directory tests/testfiles contains small test files named file_01.txt...file_03.txt. The first two files have the same modification time; the last one has a later time. These files are not yet used; they will be used to test file system content syndication.
The subscription tests are written from the point of view of the subscriber. A new subscriber is created; it "talks" to the syndicator running on the Tomcat server. Before each test, the subscriber requests a catalog and accepts two subscription offers.
| <= Previous | Next => | Table of Contents |
|