|
iPAM Developer Documentation
|
|
- Product Overview |
Product structure is central to the interoperation of iPAM agents. The purpose of iPAM is to:
- gather the information used to create the product as in the case of Input modules
- aggregate the product and organize it for presentation to the user as in the case of Handler modules
- deliver the product over various channels and media as in the case of Output modules
- schedule tasks and perform file management as in the case of the executive.
Products are defined by two interfaces of the package org.mitre.pam.interfaces. The
Product
interface defines the minimum required set of methods supported by Product classes. TheContainerProduct
interface defines additional methods to be implemented by products that contain other products.There are three classes that implement the Product/ContainerProduct realization in iPAM. These classes should be instantiated indirectly by using the ProductFactory obtained via an executive callback. The product classes are BasicProduct and VectorProduct. BasicProduct implements the Product interface and directly encapsulates String data, URL content, or File content. The VectorProduct is a container of other products (including VectorProducts). There was another type of product, a HashtableProduct, but it was never used and will be eventually removed from iPAM.
These classes allow an internal hierarchical product structure of a general nature that can "contain" a variety of information from different sources. The product structure must be rendered into an appropriate form before distribution. This rendering is performentd by product visitors.
The remainder of this page describes:
All products, regardless of type can "carry" metadata about the product. This metadata is carried as a set of attribute-value pairs. The following product attributes are always available:
id
- The identifier or product name, automatically created by all input agents/input agents
lifeTimeLong
- Lifetime in milliseconds for the product. This attribute is only used by a few agents such as the archive juggler and the putBackWeb output agent.
description
- Most input agents provide a description for each product.
Additional product attributes may be created by the user. Using the BERT gui the user can "stamp" products via any input agent or Handler. The BERT gui allows the user to create special agent attributes that are interpreted as product attributes. If the agent attribute starts with "
product_
" then the attribute is "stamped" onto the product created by the input agent or the product being handled by the Handler. For example, to create a product attribute called "latitude" the user can go to the input agent that accepts the product and create an input agent prperty called "product_latitude
".There are iPAM handlers that can use product attributes to perform filtering, selectively passing or rejecting products based on this metadata.
Product visitors are used to create a data or file structure that is meaningful to the distribtuion medium (e.g. e-mail, BackWeb, PointCast) and to the end user. In general a product visitor is created to "browse" an existing product. It may then create the files and data required to submit that product for delivery to the end user. The internal representation of the product within iPAM will not generally be delivered to the end user.The external rendered view of a product seen by the user depends mainly upon which product visitors have been called to structure and organize the product so that output agents can deliver it to the user. Product visitors tailor the product for delivery by a specific output agent by creating data, auxiliary, and configuration files that may be needed by various distribution media. Product visitors are instantiated by output agents to help them perform lower-level manipulation of the product so that it reaches the user in a readable, useable form. There are 9 product visitors.
Here is a list of product visitors and a short description of what they do. Product visistors are located in the Java package org.mitre.pam.productVisitor.
- AsBWInfoFlash -- creates the script for a BackWeb InfoFlash sprite
- AsBWInfopak -- creates a BackWeb Infopak
- AsFlatFileList -- creates a flat list of products that contain FileRefs
- AsFlatURLList -- creates a flat list of products that contain URLs
- AsLocalProduct -- creates a list of products that are all locally accessible
- AsHTMLIndex -- creates an .html page that summarizes the hierachical content of a root product container
- AsPlainText -- creates a structured view of the product using only text
- AsTree -- computes the depth and leaf count of a product hierarchy
- AsZipFile -- creates a zip file containing the contents of its products as well as a text description of the product
Product visitors are different than agents because they have no state and are not configurable through iPAM configuration files. Product visitors are more like "helpers" for agents to perform certain product related tasks.
The agent creating a product provides an id and description during instantiation. Additionally, an agent may also set the modification date and lifetime of the product. An agent may also add arbitrary String-valued properties to the product. The property name can be any String and the value associated with that property name can be any String. The default lifetime of a product is 3 days. Product lifetime is stored internally in seconds.
All products can have arbitrary properties in addition to the id, description, modificationDate, and lifetime. A general mechanism exists for adding and retrieving properties on any product. The meaning of such properties does not have to be known to the iPAM executive or to the products themselves. This allows input agents, for example, to attach properties for potential use by subsequent handlers or output agents.
The VectorProduct itself has id, description, modificationDate, lifetime, and other properties just like any product. As a ContainerProduct the VectorProduct has methods to allow adding and removing from its internal list of products. Furthermore, like all ContainerProducts, the VectorProduct has a generic method for "applying" ProductFilters to itself. The VectorProduct iterates in breadth-first fashion over all of its contents and applies the ProductFilter which can be built by the developer to accomplish a variety of tasks. The ProductFilter will not be described further here.
Input Agent Responsibilities
- input agents are responsible for retrieving information from remote or local sources and creating a product from it.
Handler Responsibilities
- Handlers are responsible for structuring, organizing, modifying, and filtering the product based on its abstract hierarchical internal representation.
- Handlers are only concerned with manipulating the internal representation of the product.
- Handlers are not concerned with the external rendered view of the product seen by the user. (This the concern of the ProductVisitors and output agents).
ProductVisitor Responsibilities
- ProductVisitors are responsible for returning a new product or other information tailored to the needs of specific output agents and output media and/or protocols so that the output agent can deliver the requisite information. ProductVisitors may also have to create certain support and auxiliary files which are needed by BackWeb and PointCast push servers.
- ProductVisitors satisfy the needs of their clients, typically output agents. Usually they are only concerned with creating an external representation of a product.
- Various ProductVisitors may be instantiated by the output agent as needed to help it perform its task.
- ProductVisitors and output agents are responsible for the external rendered view of the product seen by the user.
Output Agent Responsibilities
- Output agents are responsible for delivering the product to various push media like e-mail, BackWeb, and PointCast so that the information reaches the user.
- Output agents are also responsible for instantiating the appropriate ProductVisitors to create a useful external view of the product for the user.
Input Agent Responsibilities
- Input agents are responsible for making sure that expiration dates for products are consistent throughout a product so that if we check the expiration date of a composite product and it is expired, then we can assume that all of the subproducts within the composite product are also expired. (This rule may be changed in the future)
Handler Responsibilities
- Handlers are responsible for making sure that no empty container products are passed through. Instead, a null product should be returned if the composite product is empty. Empty composite products are not allowed.
- Handlers should be careful when they modify a product. In general the output of an input agent may be used "simultaneously" by more than one Handler. (The output of any Source may be used by more than one Sink). If a Handler needs to modify its reference to a product it may be best to clone the product and then modify the copy. However, unique product tags may be applied without cloning since other Sink agents (Handlers or output agents) would ignore tags they do not recognize.
ProductVisitor Responsibilities
- ProductVistors are just supposed to "visit" a product in order to create a form of the product that is tailored and formatted for use by a specific output agent. ProductVisitors should not change the product that they visit. ProductVisitors "return" different things depending on their visitation.
Output agent Responsibilities
- Output agents are responsible for dereferencing any unused FileRefs after they have completed sending their products, so that iPAM's garbage collection can remove the persistent files cached on the local disk which no longer have references from iPAM agents pointing to them.
Revised: 30 September 1999