com.arsdigita.cms
Class ContentItem

java.lang.Object
  extended bycom.arsdigita.domain.DomainObject
      extended bycom.arsdigita.domain.ObservableDomainObject
          extended bycom.arsdigita.kernel.ACSObject
              extended bycom.arsdigita.versioning.VersionedACSObject
                  extended bycom.arsdigita.cms.ContentItem
All Implemented Interfaces:
com.arsdigita.auditing.Audited, CustomCopy
Direct Known Subclasses:
ArticleImageAssociation, Asset, ContentBundle, ContentGroup, ContentGroupAssociation, ContentPage, Folder

public class ContentItem
extends com.arsdigita.versioning.VersionedACSObject
implements CustomCopy

This class represents a content item.

Publishing Items

The publish(LifecycleDefinition,java.util.Date) method can be used to schedule the item for publication. The publication of an item proceeds in two steps: 1. Pending Version A pending version is immediately created for the item, and each subitem of the item. When the internal createPendingVersion method is called, the content item will attempt to clone itself in order to create the pending version. First, the item will clone itself and all of its scalar attributes.Then, the item will clone all of its composite relations. After that, the item will copy all of its non-composite associations "by reference". If a target of any association is a ContentItem, the cloned item will reference the live or pending version of the target item. For example, consider Articles A and B, both of which reference an ImageAsset I:
 A ---> I <--- B
 
When A is published, creating a pending version A', I will be published as well:
 A ---> I <--- B
 A'---> I'
 
When B is later published as B', B' will reference I':
 A ---> I <--- B
 A'---> I'<--- B'
 
In order to work correctly with the automatic publishing code, every subclass of ContentItem (such as "FooItem extends ContentItem") must adhere to the following guidelines: After the pending version is created, the version copier will assign it a new lifecycle, based on the values passed in to publish(LifecycleDefinition, java.util.Date), but only if the new pending version is a regular aggregation (not a composition). In theory, it should make no difference whether the new pending version is a composition or not; however, some bugs within the publishing code currently prevent this from working correctly. For this reason, it is critically important to pass the right parameter to ItemCopier.copy(com.arsdigita.cms.CustomCopy, com.arsdigita.cms.CustomCopy, com.arsdigita.domain.DomainObject, com.arsdigita.persistence.metadata.Property) the copyProperty(ContentItem, String, ItemCopier) method. 2. Live Version When the lifecycle finally rolls around to the start date specified in the publish method, the pending versions for the item and all the subitems will be promoted to live, and the item will appear on the live site. Another publishing bug currently makes it a requirement to reload the original item from the database after it has been successfully published; I am working on fixing this. 3. Unpublishing When the lifecycle for an item expires, its live version is deleted and removed from the live site, along with all its subitems. 4. Future work The new data model makes it possible to have multiple pending versions for a content item; it should also be theoretically possible to archive expired live versions, as opposed to deletin g them. There are no Java APIs for this functionality as of yet, however.

Copying Items

The ItemCopier.copy(com.arsdigita.cms.CustomCopy, com.arsdigita.cms.CustomCopy, com.arsdigita.domain.DomainObject, com.arsdigita.persistence.metadata.Property) method may be used to create a nearly identical copy of the item, according to the rules described above. The new item will be a full-fledged, standalone item. Note that the services (such as categories) will not be automatically transferred to the new copy of the item; the copyServicesFrom(ContentItem) method must be called on the new item to transfer the services. Calling this method is not a requirement, however.

Version:
$Id: //cms/dev/src/com/arsdigita/cms/ContentItem.java#106 $
Author:
Uday Mathur, Jack Chung, Michael Pih, Stanislav Freidin <sfreidin@redhat.com>

Field Summary
static String ANCESTORS
           
static String AUDITING
           
static String BASE_DATA_OBJECT_TYPE
           
static String CHILDREN
           
static String CONTENT_SECTION
           
static String CONTENT_TYPE
           
static String DRAFT
          A state marking the draft or master item corresponding to a live or pending version of that item.
static String DRAFT_VERSION
           
static String LANGUAGE
           
static String LIVE
          A state marking the live version, a copy of the draft item.
static String NAME
           
static String PARENT
           
static String PENDING
          A state marking the live version, a copy of the draft item.
static String VERSION
           
static String versionId
           
static String VERSIONS
           
 
Fields inherited from class com.arsdigita.versioning.VersionedACSObject
IS_DELETED, MASTER
 
Fields inherited from class com.arsdigita.kernel.ACSObject
CONTAINER, DEFAULT_DOMAIN_CLASS, DISPLAY_NAME, ID, OBJECT_TYPE
 
Constructor Summary
ContentItem()
          Default constructor.
ContentItem(BigDecimal id)
          Constructor.
ContentItem(com.arsdigita.persistence.DataObject obj)
          Constructor.
ContentItem(com.arsdigita.persistence.OID oid)
          Constructor.
ContentItem(String type)
          Constructor.
 
Method Summary
 void addCategory(com.arsdigita.categorization.Category category)
          Adds a category to this content item (or its bundle if one exists)
protected  void addPendingVersion(ContentItem version)
          Adds a pending version to the item.
protected  void afterSave()
           
 void assertDraft()
          Assert that this item is a draft version
 void assertLive()
          Assert that this item is a live version
 void assertMaster()
          Deprecated. with no replacement
 void assertPending()
          Assert that this item is a pending version
protected  void beforeDelete()
          Remove any Links pointing to this item before deletion.
protected  void beforeSave()
          For new content items, sets the associated content type if it has not been already set.
protected  boolean canPublishToFS()
          Method to determine whether this ContentItem should be automatically published to the file system.
 ContentItem copy()
          Recursively copy this item, creating a clone.
 ContentItem copy(ContentItem newParent, boolean copyServices)
          Recursively copy this item, creating a clone.
protected  boolean copyProperty(ContentItem source, String attribute, ItemCopier copier)
          Deprecated. use copyProperty(CustomCopy, Property, ItemCopier) instead
 boolean copyProperty(CustomCopy source, com.arsdigita.persistence.metadata.Property property, ItemCopier copier)
          Copy the specified property (attribute or association) from the specified source item.
 boolean copyServices(ContentItem srcItem)
          Copy services from the source item.
 void copyServicesFrom(ContentItem source)
          Transfer services, such as categories, from the passed-in item to this item.
 ContentItem createLiveVersion()
          Recursively copy this item, creating a live version.
protected  ContentItem createPendingVersion(Lifecycle cycle)
          Recursively copy this item, creating a pending version.
 Object get(String key)
          Publicized getter method for use by metadata forms.
 String getBaseDataObjectType()
           
 Iterator getCategories(String useContext)
          Returns an iterator over the categories associated with this content item which is associated with the given use context
 com.arsdigita.categorization.CategoryCollection getCategoryCollection()
           
 ItemCollection getChildren()
          Fetches all the child items of this item.
 ContentSection getContentSection()
          Returns the content section to which this item belongs.
 ContentType getContentType()
          Gets the content type of this content item.
 Date getCreationDate()
          Gets the creation date of the object.
 String getCreationIP()
          Gets the IP address associated with creating an object.
 com.arsdigita.kernel.User getCreationUser()
          Gets the user who created the object.
 String getDisplayName()
          Fetch the display name of the content item.
 ContentItem getDraftVersion()
          Returns the DRAFT version of this content item.
 String getLanguage()
          Language of the content item.
 Date getLastModifiedDate()
          Gets the last modified date.
 String getLastModifiedIP()
          Gets the last modified IP address.
 com.arsdigita.kernel.User getLastModifiedUser()
          Gets the user who last modified the object.
 Lifecycle getLifecycle()
          Fetches the publication lifecycle.
 ContentItem getLiveVersion()
          Fetches the live version of this content item.
 com.arsdigita.globalization.Locale getLocale()
          Get the locale for this content item.
 String getName()
          Fetches the name of the content item.
 com.arsdigita.kernel.ACSObject getParent()
          Get the parent object.
 String getPath()
          Return the path to the item starting at its root.
 ItemCollection getPathInfo()
          Return a collection of ancestors starting from the item's root to the item's parent item.
 ItemCollection getPathInfo(boolean includeSelf)
          Return a collection of ancestors starting from the item's root to the item's parent item (if includeSelf is false) or to the item itself otherwise.
 String getPathNoJsp()
           
 ItemCollection getPendingVersions()
          Fetches the pending versions, if any, of this content item.
 ContentItem getPublicVersion()
          Get the live version for the item.
 String getVersion()
          Gets the version tag.
 ContentItem getWorkingVersion()
          Deprecated. use getDraftVersion() instead
protected  void initialize()
          Called from the base class (DomainObject) constructors.
 boolean isDraftVersion()
          Returns true if this item is a DRAFT version.
 boolean isLive()
          Returns true if this item has a publicly viewable version.
 boolean isLiveVersion()
          Returns true if this item is a LIVE version.
 boolean isPendingVersion()
          Returns true if this item is a PENDING version.
 boolean isPublished()
          Return true if this item has been published.
protected  ContentItem makeCopy()
          Performs the actual mechanics of copying a content item.
 void promotePendingVersion(ContentItem pending)
          Promote the specified pending version to live.
 ContentItem publish(LifecycleDefinition cycleDef, Date startDate)
          Schedules an item for publication.
protected  void publishToFS()
          Publish this item to the filesystem; can only be called on a live version.
 void removeCategory(com.arsdigita.categorization.Category category)
          Removes a category from this content item (or its bundle if one exists)
 void removeLifecycle(ContentItem itemToRemove)
          Remove the associated lifecycle.
 void removePendingVersion(ContentItem version)
          Removes a pending version from the item.
 void set(String key, Object value)
          Public setter method for use by metadata forms.
 void setContentSection(ContentSection section)
          Set the content section of an item.
 void setContentType(ContentType type)
          Sets the content type of this content item.
 void setDefaultCategory(com.arsdigita.categorization.Category category)
          Sets a category as the default/primary category for this item.
 void setLanguage(String language)
          Set the language of the content item.
 void setLifecycle(Lifecycle lifecycle)
          Apply a lifecycle to this content item.
 void setLive(ContentItem version)
          Makes an item live or not live.
protected  void setLiveVersion(ContentItem version)
          Sets the live version.
 void setName(String value)
          Sets the name of the content item.
 void setParent(com.arsdigita.kernel.ACSObject object)
          Set the parent object.
protected  void setVersion(String version)
          Sets the version tag.
protected  void setVersionRecursively(String version)
          Recursively update the version attribute of the current content item to the new value.
 void unpublish()
          Unpublishes an item.
protected  void unpublishFromFS()
           
 
Methods inherited from class com.arsdigita.versioning.VersionedACSObject
applyTag, applyUniqueTag, autoPropagateMaster, getMaster, getRolledBackTo, getTransactions, getTransactions, isMaster, isRolledBack, isSubtype, permanentlyDelete, propagateMaster, recordAttributeChange, rollBackTo, rollBackTo, rollForward, save, setMaster, trackChanges
 
Methods inherited from class com.arsdigita.kernel.ACSObject
assertPrivilege, checkPrivilege, doCreateCheck, doWriteCheck, getContainer, getDefaultDomainClass, getID, getSpecificObjectType, getSpecificOID, gimmeContainer, isContainerModified, setID, setID
 
Methods inherited from class com.arsdigita.domain.ObservableDomainObject
addObserver, getObservers
 
Methods inherited from class com.arsdigita.domain.DomainObject
add, add, addToAssociation, afterDelete, clear, delete, disconnect, equals, getObjectType, getOID, getSession, hashCode, isDeleted, isDisconnected, isModified, isNew, isPropertyModified, isValid, remove, remove, remove, removeFromAssociation, save, setAssociation, setAssociation, specializeDataObject, specializeDataObject, toString
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

versionId

public static final String versionId
See Also:
Constant Field Values

BASE_DATA_OBJECT_TYPE

public static final String BASE_DATA_OBJECT_TYPE
See Also:
Constant Field Values

DRAFT

public static final String DRAFT
A state marking the draft or master item corresponding to a live or pending version of that item.

See Also:
Constant Field Values

LIVE

public static final String LIVE
A state marking the live version, a copy of the draft item.

See Also:
Constant Field Values

PENDING

public static final String PENDING
A state marking the live version, a copy of the draft item.

See Also:
Constant Field Values

ANCESTORS

public static final String ANCESTORS
See Also:
Constant Field Values

PARENT

public static final String PARENT
See Also:
Constant Field Values

CHILDREN

public static final String CHILDREN
See Also:
Constant Field Values

CONTENT_TYPE

public static final String CONTENT_TYPE
See Also:
Constant Field Values

VERSION

public static final String VERSION
See Also:
Constant Field Values

NAME

public static final String NAME
See Also:
Constant Field Values

LANGUAGE

public static final String LANGUAGE
See Also:
Constant Field Values

AUDITING

public static final String AUDITING
See Also:
Constant Field Values

DRAFT_VERSION

public static final String DRAFT_VERSION
See Also:
Constant Field Values

VERSIONS

public static final String VERSIONS
See Also:
Constant Field Values

CONTENT_SECTION

public static final String CONTENT_SECTION
See Also:
Constant Field Values
Constructor Detail

ContentItem

public ContentItem()
Default constructor. This creates a new content item.


ContentItem

public ContentItem(com.arsdigita.persistence.OID oid)
            throws com.arsdigita.domain.DataObjectNotFoundException
Constructor. The contained DataObject is retrieved from the persistent storage mechanism with an OID specified by oid.

Parameters:
oid - The OID for the retrieved DataObject

ContentItem

public ContentItem(BigDecimal id)
            throws com.arsdigita.domain.DataObjectNotFoundException
Constructor. The contained DataObject is retrieved from the persistent storage mechanism with an OID specified by id and ContentItem.BASE_DATA_OBJECT_TYPE.

Parameters:
id - The id for the retrieved DataObject

ContentItem

public ContentItem(com.arsdigita.persistence.DataObject obj)
Constructor. Retrieves or creates a content item using the DataObject argument.

Parameters:
obj - The DataObject with which to create or load a content item

ContentItem

public ContentItem(String type)
Constructor. Creates a new content item using the given data object type. Such items are created as draft versions.

Parameters:
type - The String data object type of the item to create
Method Detail

initialize

protected void initialize()
Called from the base class (DomainObject) constructors.


getBaseDataObjectType

public String getBaseDataObjectType()
Returns:
the base PDL object type for this item. Child classes should override this method to return the correct value

get

public Object get(String key)
Publicized getter method for use by metadata forms.


set

public void set(String key,
                Object value)
Public setter method for use by metadata forms.


beforeSave

protected void beforeSave()
For new content items, sets the associated content type if it has not been already set.


afterSave

protected void afterSave()

getDisplayName

public String getDisplayName()
Fetch the display name of the content item. The display name for a ContentItem is the name property.

Returns:
The name of the content item

getName

public String getName()
Fetches the name of the content item.

Returns:
The name of the content item

setName

public void setName(String value)
Sets the name of the content item.

Parameters:
value - The name of the content item

getParent

public com.arsdigita.kernel.ACSObject getParent()
Get the parent object.


setParent

public final void setParent(com.arsdigita.kernel.ACSObject object)
Set the parent object.

Parameters:
object - The ACSObject parent

getChildren

public final ItemCollection getChildren()
Fetches all the child items of this item.

Returns:
an ItemCollection of children

getContentType

public ContentType getContentType()
Gets the content type of this content item.


setContentType

public void setContentType(ContentType type)
Sets the content type of this content item.

Parameters:
type - The content type

getContentSection

public ContentSection getContentSection()
Returns the content section to which this item belongs. Fetches the denormalized content section of an item. If one is not found, this method returns null. Since cms_items.section_id is a denormalization, this method may return null even if the item "belongs" to a content section. For example, calling getContentSection() on an Article's ImageAsset will return null even though the image asset should belong to the same section as the article.

Returns:
The content section to which this item belongs

setContentSection

public final void setContentSection(ContentSection section)
Set the content section of an item.

Parameters:
section - The content section

getPath

public String getPath()
Return the path to the item starting at its root. The path is absolute, of the form /x/y/z where x and y are the names of the item's grandparent and parent respectively, and z is the name of the item itself. The item's root is the ancestor reachable through repeated getParent() calls whose parent is null. This is usually a folder, but may be any ACSObject. Note that the name of the root folder of the content section where the item resides is not included in the path.

Returns:
the path from the item's root to the item
See Also:
getPathInfo(boolean)

getPathNoJsp

public String getPathNoJsp()
Returns:
the path from the item's root to the item
See Also:
getPathInfo(boolean)

getPathInfo

public ItemCollection getPathInfo()
Return a collection of ancestors starting from the item's root to the item's parent item. For items contained in folders this is similar to a directory path to the item. The collection starts with the root item and ends with the item's direct parent.

The item's root is the ancestor reachable through repeated getParent() calls whose parent is null. This is usually a folder, but may be any ACSObject.

Returns:
the collection of the item's ancestors.
See Also:
getPathInfo(boolean)

getPathInfo

public ItemCollection getPathInfo(boolean includeSelf)
Return a collection of ancestors starting from the item's root to the item's parent item (if includeSelf is false) or to the item itself otherwise. For items contained in folders this is similar to a directory path to the item. The collection starts with the root item and ends with the item's direct parent.

The item's root is the ancestor reachable through repeated getParent() calls whose parent is null. This is usually a folder, but may be any ACSObject.

Parameters:
includeSelf - a boolean value.
Returns:
the items on the path to the root folder.

getVersion

public String getVersion()
Gets the version tag.


setVersion

protected void setVersion(String version)
Sets the version tag.

Parameters:
version - A version tag, LIVE or DRAFT or PENDING

isDraftVersion

public boolean isDraftVersion()
Returns true if this item is a DRAFT version.

Returns:
true if this item is a DRAFT version

getDraftVersion

public ContentItem getDraftVersion()
Returns the DRAFT version of this content item.

Returns:
the draft version

getWorkingVersion

public ContentItem getWorkingVersion()
Deprecated. use getDraftVersion() instead

Fetches the draft (aka, "master" or "working") version of this content item.

Returns:
the working version representation of the ContentItem, possibly this item

isPendingVersion

public boolean isPendingVersion()
Returns true if this item is a PENDING version.

Returns:
true if this is one of the pending versions

getPendingVersions

public ItemCollection getPendingVersions()

Fetches the pending versions, if any, of this content item. The versions are returned in chronological order, sorted by their respective lifecycle's start date.

Returns:
the collection of pending versions for this item

addPendingVersion

protected void addPendingVersion(ContentItem version)
Adds a pending version to the item.


removePendingVersion

public void removePendingVersion(ContentItem version)
Removes a pending version from the item.

Parameters:
version - the version to remove

isLiveVersion

public boolean isLiveVersion()
Returns true if this item is a LIVE version.

Returns:
true if this is the live version

getLiveVersion

public ContentItem getLiveVersion()
Fetches the live version of this content item. Returns null if there is none.

Returns:
a ContentItem representing the live version

setLiveVersion

protected void setLiveVersion(ContentItem version)
Sets the live version.

Parameters:
version - The ContentItem to set live

getPublicVersion

public ContentItem getPublicVersion()
Get the live version for the item. If no live version exists, return the latest pending version, if any.

Returns:
the public version for this item, or null if none

canPublishToFS

protected boolean canPublishToFS()
Method to determine whether this ContentItem should be automatically published to the file system.


publishToFS

protected void publishToFS()
Publish this item to the filesystem; can only be called on a live version.


unpublishFromFS

protected void unpublishFromFS()

isLive

public boolean isLive()
Returns true if this item has a publicly viewable version. This item is not necessarily the live version nor is this method to be confused with isPublished.

Returns:
true if this content item has a live version, or if it is the live version

setLive

public void setLive(ContentItem version)
Makes an item live or not live.

Parameters:
version - the version which should become live, null to make the item non-live

publish

public ContentItem publish(LifecycleDefinition cycleDef,
                           Date startDate)
Schedules an item for publication.

Parameters:
cycleDef - The lifecycle definition
startDate - The time to schedule the start of the lifecycle. If null, use the current time as the start date.
Returns:
the new pending version

unpublish

public void unpublish()
Unpublishes an item. This method removes the item's lifecycle and removes all pending versions. It is intended for use in UI code, and it should not be used for making items go "unlive". Instead, use setLive(null).


getLifecycle

public Lifecycle getLifecycle()
Fetches the publication lifecycle.

Returns:
The associated lifecycle, null if there is none

isPublished

public boolean isPublished()
Return true if this item has been published.

Returns:
true if this item has a lifecycle, false otherwise

setLifecycle

public void setLifecycle(Lifecycle lifecycle)
Apply a lifecycle to this content item.

Parameters:
lifecycle - The lifecycle

removeLifecycle

public void removeLifecycle(ContentItem itemToRemove)
Remove the associated lifecycle.


getCategoryCollection

public com.arsdigita.categorization.CategoryCollection getCategoryCollection()
Returns:
all categories to which this item belongs

getCategories

public Iterator getCategories(String useContext)
Returns an iterator over the categories associated with this content item which is associated with the given use context

Parameters:
useContext - the category use context
Returns:
An iterator over all Categories to which this item belongs

setDefaultCategory

public void setDefaultCategory(com.arsdigita.categorization.Category category)
Sets a category as the default/primary category for this item. Actual default assignment is performed on the bundle if one exists. If this category is not already assigned to this item, then this method also adds the category to the item.

Parameters:
category - The category to set as the default.

addCategory

public void addCategory(com.arsdigita.categorization.Category category)
Adds a category to this content item (or its bundle if one exists)

Parameters:
category - The category to add this item to

removeCategory

public void removeCategory(com.arsdigita.categorization.Category category)
Removes a category from this content item (or its bundle if one exists)

Parameters:
category - The category to remove this item from

copy

public ContentItem copy()
Recursively copy this item, creating a clone. Reassign composite associations from the copy to point to the copies of original items. This method will not automatically transfer services (such as categories) to the copy; the copyServicesFrom(ContentItem) method should be called to accomplish this.

NOTE: This method will also save the item and all of its unpublished subitems. NOTE: This method should be final with the addition of makeCopy, but is not just in case there are extensions in some PS code. The 'non-finalness' of this method should be considered deprecated.

Returns:
the live version for this item
See Also:
copyServicesFrom(ContentItem)

copy

public final ContentItem copy(ContentItem newParent,
                              boolean copyServices)
Recursively copy this item, creating a clone. Reassign composite associations from the copy to point to the copies of original items.

NOTE: This method will save the item and all of its unpublished subitems.

Parameters:
newParent - The new parent item for this item
copyServices - Copy services if true
Returns:
the new copy of the item
See Also:
copyServicesFrom(ContentItem)

makeCopy

protected ContentItem makeCopy()
Performs the actual mechanics of copying a content item. Non-final so that subtypes can extend copying behavior.

Returns:
A new copy of the item

copyServicesFrom

public void copyServicesFrom(ContentItem source)
Transfer services, such as categories, from the passed-in item to this item. This method should be called immediately after ItemCopier.copy(com.arsdigita.cms.CustomCopy, com.arsdigita.cms.CustomCopy, com.arsdigita.domain.DomainObject, com.arsdigita.persistence.metadata.Property), as follows:
 Article newArticle = (Article)oldArticle.copyItem();
 newArticle.copyServicesFrom(oldArticle);

WARNING: This method will most likely crash if you call it twice in a row.

Parameters:
source - the ContentItem whose services will be copied
See Also:
copy()

createPendingVersion

protected ContentItem createPendingVersion(Lifecycle cycle)
Recursively copy this item, creating a pending version. Reassign composite associations from the pending version to point to the pending/live versions of other items. NOTE: This method will also save the item and all of its unpublished subitems.

Parameters:
cycle - the lifecycle to use. A null cycle implies that a live version should be created.
Returns:
the new pending version for this item

promotePendingVersion

public void promotePendingVersion(ContentItem pending)
Promote the specified pending version to live. Delete the old live version, if any.

Parameters:
pending - The pending item to promote

setVersionRecursively

protected void setVersionRecursively(String version)
Recursively update the version attribute of the current content item to the new value. Used by the lifecycle listener to promote a pending version to live.

Parameters:
version - The new Version to set

createLiveVersion

public ContentItem createLiveVersion()
Recursively copy this item, creating a live version. Reassign component associations from the live version to point to the live versions of other items.

Returns:
the live version for this item

copyProperty

protected final boolean copyProperty(ContentItem source,
                                     String attribute,
                                     ItemCopier copier)
Deprecated. use copyProperty(CustomCopy, Property, ItemCopier) instead

Copy the specified property (attribute or association) from the specified source item. This method almost completely overrides the metadata-driven methods in ObjectCopier. ... ObjectCopier will no longer call it, so existing implementations need to update to the new signature


copyProperty

public boolean copyProperty(CustomCopy source,
                            com.arsdigita.persistence.metadata.Property property,
                            ItemCopier copier)
Copy the specified property (attribute or association) from the specified source item. This method almost completely overrides the metadata-driven methods in ObjectCopier. If the property in question is an association to ContentItem(s), this method should only call FooContentItem newChild = copier.copy(srcItem, this, riginalChild, property); An attempt to call any other method in order to copy the child will most likely have disastrous consequences. In fact, this copier method should generally be called for any DomainObject copies, later making custom changes, unless the copying behavior itself is different from the default (or the item should not be copied at all at this point). If a subclass of a class which implements CustomCopy overrides this method, it should return super.copyProperty for properties which do not need custom behavior in order to indicate that it is not interested in handling the property in any special way. As a hypothetical example (no longer reflected in Article itself), the Article class extends ContentItem. It defines an association to 0..n ImageAsset. Unfortunately, the association has "order_n" and "caption" link attributes, which cannot be copied automatically, since the persistence system doesn't know enough about them. The following sample code from the Article class ensures that images are copied correctly:

 public boolean copyProperty(CustomCopy srcItem, Property property, ItemCopier copier) {

  String attrName = property.getname()
   // We only care about copying images; all other properties should
   // be handled in a default manner
   if (!attrName.equals(IMAGES))
     return super.copyProperty(srcItem, property, copier);

   // The source item is guaranteed to be of the correct type
   Article src = (Article)srcItem;

   // Retrieve images from the source
   ImageAssetCollection srcImages = src.getImages();

   // Copy each image using the passed-in copier
   while(srcImages.next()) {
     ImageAsset srcImage = srcImages.getImage();

     // Images may be shared between items, and so they are not
     // composite. Thus, we are going to pass false to the object
     // copier in the second parameter
     ImageAsset newImage = (ImageAsset)copier.copy(srcItem, this, srcImage, property);

     // Add the new image to the new item
     addImage(newImage, src.getCaption(srcImage));
   }

   // Tell the automated copying service that we have handled this
   // property
   return true;
 }
 
Note that for top-level item associations, VersionCopier will return null since the actual associatons are only created at "go live" time, so the ability to override behavior for top-level item associations is somewhat limited. A common case for needing to override copyProperty to handle these associations would be to auto-publish the target of the association but still handle the association updating normally. In this case, copyProperty would call publish() separately on the associated object, and then return false to indicate that the copier should continue to handle the association normally.

Specified by:
copyProperty in interface CustomCopy
Parameters:
source - the source CustomCopy item
property - the property to copy
copier - a temporary class that is able to copy a child item correctly.
Returns:
true if the property was copied; false to indicate that regular metadata-driven methods should be used to copy the property.

copyServices

public boolean copyServices(ContentItem srcItem)
Copy services from the source item. This method is the analogue of the copyProperty(com.arsdigita.cms.ContentItem, java.lang.String, com.arsdigita.cms.ItemCopier) method above. The object copier will call this method whenever an item has been successfully published, in order to transfer services such as categorization or permissions to the live version.

This method is requied to return false to signal the object copier to transfer default services from the source item; or true in order to abort further processing of services.

Returns:
true to tell the object copier to stop copying services for this item, false otherwise

getLanguage

public String getLanguage()
Language of the content item.

Returns:
ISO639 2-letter language code

setLanguage

public void setLanguage(String language)
Set the language of the content item.

Parameters:
language - ISO639 2-letter language code

getLocale

public com.arsdigita.globalization.Locale getLocale()
Get the locale for this content item.

Returns:
The locale of the item

assertDraft

public final void assertDraft()
Assert that this item is a draft version


assertPending

public final void assertPending()
Assert that this item is a pending version


assertLive

public final void assertLive()
Assert that this item is a live version


assertMaster

public final void assertMaster()
Deprecated. with no replacement

Assert that this item is a top-level master object


beforeDelete

protected void beforeDelete()
Remove any Links pointing to this item before deletion. XXX This should go away when one-way association targets can specify the equivalent of on delete set null


getCreationUser

public com.arsdigita.kernel.User getCreationUser()
Gets the user who created the object. May be null.

Specified by:
getCreationUser in interface com.arsdigita.auditing.Audited
Returns:
the user who created the object.

getCreationDate

public Date getCreationDate()
Gets the creation date of the object.

Specified by:
getCreationDate in interface com.arsdigita.auditing.Audited
Returns:
the creation date.

getCreationIP

public String getCreationIP()
Gets the IP address associated with creating an object. May be null.

Specified by:
getCreationIP in interface com.arsdigita.auditing.Audited
Returns:
the creation IP address.

getLastModifiedUser

public com.arsdigita.kernel.User getLastModifiedUser()
Gets the user who last modified the object. May be null.

Specified by:
getLastModifiedUser in interface com.arsdigita.auditing.Audited
Returns:
the last modifying user.

getLastModifiedDate

public Date getLastModifiedDate()
Gets the last modified date.

Specified by:
getLastModifiedDate in interface com.arsdigita.auditing.Audited
Returns:
the last modified date.

getLastModifiedIP

public String getLastModifiedIP()
Gets the last modified IP address. May be null.

Specified by:
getLastModifiedIP in interface com.arsdigita.auditing.Audited
Returns:
the IP address associated with the last modification.


Copyright (c) 2004 Red Hat, Inc. Corporation. All Rights Reserved. Generated at July 21 2004:2352 UTC