The PublicationService allows you to control the publication process and to inspect the state of the publication queue.
When a content is created, it exists on the Content Management
Server only. The process of transferring the content to the
Master Live Server is referred to as
publishing the content. Before a content can be
published, it has to be approved. In general, the approval
of a content refers to its location in the folder tree. It is approved that the content appear
on the Master Live Server at a given place, hence
the name place approval for this type of approval
which can be performed by the method approvePlace(Content)
. When a document is
published, a version must be created on the Master Live
Server, too. To this end, the version itself must be approved using the method
approve(Version)
. Only an approved version can be published. Even if a content is
published, subsequent movements, renames, and property changes happen on the
Content Management Server only. New places or new versions
must be published explicitly.
When a content is supposed to leave the Master Live Server,
it must be marked for withdrawal or
deletion using the methods
toBeWithdrawn(Content)
and toBeDeleted(Content)
. After that
operation is place approved, the content can be included in a publication set. During the
subsequent publication, the content is removed from the Master Live
Server instead of being updated. In the case of a mark for deletion, it is also
moved into the archive on the Content Management Server.
A rather complex state chart is shown in Figure 5.6, “Statechart: Content Publication”. It depicts the various states with respect to publication. Being published, a content gains access to a number of attributes that are only available in this state. Its state space is fragmented into four sub spaces:
it might be moved
it might be renamed
it might be marked for being withdrawn
it might be marked for being deleted
A publication is initiated by the publish(...)
methods. You can also request a
publication preview by means of the preview(...)
methods. A preview does not
actually copy information to the Master Live Server, but
makes all checks to determine whether a publication would be successful. Possible arguments to
the publish and preview calls are a single content, a collection of contents, or a
PublicationSet.
When contents are given as argument, the actual publication set is determined heuristically. To this end, the publication service selects versions to be published with the content, if that is appropriate given the current marks and approvals. You can also create a publication set by providing collections of contents and versions explicitly, taking care that no versions are included whose content is marked for withdrawal or deletion.
After a publication has completed successfully, a PublicationResult is returned. The publication result informs about all contents that were involved in the publication and about the actions that were performed. If the publication is unsuccessful, a PublicationFailedException is thrown, which wraps a publication result that details the cause of the error.
As an example, let us look at an excerpt from the class PublicationServiceExample
that is available as a source code example:
PublicationService publisher = repository.getPublicationService(); publisher.approvePlace(folder); publisher.publish(folder); publisher.toBeDeleted(folder); publisher.approvePlace(folder); publisher.publish(folder);
A folder that has been created before is approved, published, marked for deletion, approved again, and deleted by publishing. This example summarizes the entire lifecycle of content publication in a few lines. Obviously, real applications will not use all of these methods in one place.
The publication service also provides a means to inspect the current state of the publication queue. You can get a list of all pending publications and access a summary of each publication's characteristics. A PublicationServiceListener informs about changes to the publication queue.
If you have enabled Multi-Site Management for your CoreMedia CMS, there may be more than one publication target. Each publication target represents one Master Live Server and includes any number of base folders. You can retrieve all PublicationTarget objects from the publication service. The Content Server Manual provides more information on how to set up publication targets.