content package — Content Handling Service
The content package allows
content — files, URL links, and aggregates (multiple pieces of content that
behave as a single file — to be associated with business objects. These
business objects are referred to as ContentHolders. It appears to users that
content is contained in the business objects. The content itself is treated
like any other attribute of the object and requires read and/or write access on
the ContentHolder.
Design Overview
The figure below is a conceptual representation of
ContentHolders and how they are represented to client developers.
ContentHolders
Each ContentHolder can be thought of as containing an
undetermined number of ContentItems. Each ContentItem can be an URLData (a
link) instance, an ApplicationData (a file) instance, or an Aggregate (a group
of content treated like a single file) instance. A ContentItem references a
format (basically the file’s MIME type; see the DataFormat class that follows)
and a WTPrincipalReference. This contains the user who created the ContentItem.
Two primary interfaces can be used when creating your
own ContentHolder classes: the ContentHolder interface and the
FormatContentHolder interface.
The ContentHolder interface is used for classes like
change request (see wt.change2.WTChangeRequest2), where content is used more as
an attachment.
The FormatContentHolder interface is used for classes
like document (see wt.doc.WTDocument), where you want to associate a primary
format with the document. This format is set automatically when using the
ContentService. For example, a document having Microsoft Word file attached as
primary content will get a format of Microsoft Word.
The ContentRoleType is an enumerated type that exists
primarily for customization. It is not used by the ContentService to perform
any particular action or behavior except in the case of FormatContentHolders.
It is used when one piece of content is to be stored as the main piece of content
for the document, as opposed to a related attachment. Primary content is, for
example, downloaded on a checkout of a document. Its role should be set as
PRIMARY before it is stored. The code to set the primary content is as follows:
ContentItem item = . . .
item.setRole(
ContentRoleType.PRIMARY );
The ContentRoleType can also be used to specify
particular ContentItems as renditions, an attached drawing, and so forth. The
default enumeration can be updated in wt/content/ContentRoleTypeRB.java.
However, for proper execution of the system, do not remove the existing values
from this resource bundle.
Note that the aggregate pieces of content are not
currently supported for customization.
The following figure is a conceptual representation of
the DataFormat class.
DataFormat Class
The DataFormat class is an Administrative class that
is used to associate a primary format with FormatContentHolders and
ContentItems. Instances of DataFormat class should have unique formatName, can be created only by an
administrator, and can never be deleted. Note that formats on files are set
based on file extension and/or mime type.
Content Services
The ContentService is available both on the client and
server side. The ContentServiceSvr is available only on the server side. The
service methods are to be referenced through the corresponding helper class.
For further information, see the javadoc for ContentService.
Working with ContentItems
Querying
The method call to get the secondary content
associated with a ContentHolder is as follows:
ContentHolder holder;
holder =
ContentHelper.service.getContents( holder );
Vector contents =
ContentHelper.getContentList( holder );
This vector contains all
the secondary ContentItems associated with the passed ContentHolder.
The method call to get the primary content associated
with a FormatContentHolder is as follows:
ContentHolder holder;
holder =
ContentHelper.service.getContents( holder );
ContentItem item =
ContentHelper.getPrimary( holder );
Creating, Updating, and Removing
PTC recommends that you set up a signed applet and
post to the content service via HTTP. The method call to set up the URL to post
to the content service is as follows:
ContentHolder holder = . . .
URL postURL =
ContentHelper.getUploadURL( holder );
To receive a stream from the ContentService, use the
following:
ContentHolder holder = . . .
URL postURL =
ContentHelper.getDownloadURL( holder );
When posting to the ContentService, the data must be
posted in a particular format. An outline of the format as is follows:
attribute name 1 attribute value 1
attribute name 2 attribute value 2
. . .
attribute name x attribute value x
content_description value <file path here>
attribute name 1 attribute value 1
attribute name 2 attribute value 2
. . .
attribute name x attribute value x
content_description value <file path here>
. . . <as many ContentItems as desired>
EndContent null <You
must mark the end with this>
The content_description line should appear as follows
for a new file:
newFile c\:path\uploaded_file.xxx file stream . . .
The content_description line should appear as follows
for an ApplicationData that already exists in the ContentHolder (that is,
replace):
fileoid c:\path\uploaded_file.xxx file stream . . .
The value for fileoid can be generated using the
following method call:
ApplicationData
applicationDataObj = . . .
String oidstr = PersistenceHelper.getObjectIdentifier(applicationDataObj
).getStringValue( );
The content_description line should appear as follows
for a new URL:
newURLLink http://xxx.yyy.zzz
The content_description line should appear as follows
for an existing URL, generating the urloid, like the one for the preceding
files:
urloid http://xxx.yyy.zzz
The ContentService currently handles the following
attributes:
roleName (see
wt.content.ContentRoleType)
remove
description
The attributes can be passed in any order, as long as
the preceding content_description line is passed last for each object being
worked on.
Business Rules
The read and modification
of content is based on the access rules of the ContentHolder.
Event Processing
At this time, the
ContentService does not broadcast any events.