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.

Figure 5.6. Statechart: Content Publication

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:

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-Master 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.