|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.arsdigita.domain.DomainObject
com.arsdigita.domain.ObservableDomainObject
com.arsdigita.kernel.ACSObject
com.arsdigita.versioning.VersionedACSObject
com.arsdigita.cms.ContentItem
This class represents a content item.
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:
When A is published, creating a pending version A', I will be published as well:A ---> I <--- B
When B is later published as B', B' will reference I':A ---> I <--- B A'---> I'
In order to work correctly with the automatic publishing code, every subclass ofA ---> I <--- B A'---> I'<--- B'
ContentItem
(such as "FooItem
extends ContentItem") must adhere to the following
guidelines:
public FooItem(DataObject obj) { super(obj); }
public FooItem(String type) { super(type); // Do more stuff here. }
copyProperty(ContentItem, String, ItemCopier)
method. For examples on how to implement it, see the methods's
javadoc and the sample implementation in the Article
class.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.
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.
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 |
public static final String versionId
public static final String BASE_DATA_OBJECT_TYPE
public static final String DRAFT
public static final String LIVE
public static final String PENDING
public static final String ANCESTORS
public static final String PARENT
public static final String CHILDREN
public static final String CONTENT_TYPE
public static final String VERSION
public static final String NAME
public static final String LANGUAGE
public static final String AUDITING
public static final String DRAFT_VERSION
public static final String VERSIONS
public static final String CONTENT_SECTION
Constructor Detail |
public ContentItem()
public ContentItem(com.arsdigita.persistence.OID oid) throws com.arsdigita.domain.DataObjectNotFoundException
DataObject
is retrieved
from the persistent storage mechanism with an OID
specified by oid
.
oid
- The OID
for the retrieved
DataObject
public ContentItem(BigDecimal id) throws com.arsdigita.domain.DataObjectNotFoundException
DataObject
is retrieved
from the persistent storage mechanism with an OID
specified by id
and
ContentItem.BASE_DATA_OBJECT_TYPE
.
id
- The id
for the retrieved
DataObject
public ContentItem(com.arsdigita.persistence.DataObject obj)
DataObject
argument.
obj
- The DataObject
with which to create or
load a content itempublic ContentItem(String type)
type
- The String
data object type of the
item to createMethod Detail |
protected void initialize()
DomainObject
)
constructors.
public String getBaseDataObjectType()
public Object get(String key)
public void set(String key, Object value)
protected void beforeSave()
protected void afterSave()
public String getDisplayName()
ContentItem
is the name property.
public String getName()
public void setName(String value)
value
- The name of the content itempublic com.arsdigita.kernel.ACSObject getParent()
public final void setParent(com.arsdigita.kernel.ACSObject object)
object
- The ACSObject
parentpublic final ItemCollection getChildren()
ItemCollection
of childrenpublic ContentType getContentType()
public void setContentType(ContentType type)
type
- The content typepublic ContentSection getContentSection()
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.
public final void setContentSection(ContentSection section)
section
- The content sectionpublic String getPath()
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.
getPathInfo(boolean)
public String getPathNoJsp()
getPathInfo(boolean)
public ItemCollection getPathInfo()
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
.
getPathInfo(boolean)
public ItemCollection getPathInfo(boolean includeSelf)
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
.
includeSelf
- a boolean
value.
public String getVersion()
protected void setVersion(String version)
version
- A version tag, LIVE
or DRAFT
or PENDING
public boolean isDraftVersion()
true
if this item is a DRAFT
version.
true
if this item is a DRAFT
versionpublic ContentItem getDraftVersion()
DRAFT
version of this content item.
public ContentItem getWorkingVersion()
getDraftVersion()
instead
ContentItem
, possibly this itempublic boolean isPendingVersion()
true
if this item is a
PENDING
version.
true
if this
is one of the
pending versionspublic 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.
protected void addPendingVersion(ContentItem version)
public void removePendingVersion(ContentItem version)
version
- the version to removepublic boolean isLiveVersion()
true
if this item is a LIVE
version.
true
if this
is the live
versionpublic ContentItem getLiveVersion()
ContentItem
representing the live
versionprotected void setLiveVersion(ContentItem version)
version
- The ContentItem
to set livepublic ContentItem getPublicVersion()
protected boolean canPublishToFS()
protected void publishToFS()
protected void unpublishFromFS()
public boolean isLive()
true if this content item has a live
version, or if it is the live version
public void setLive(ContentItem version)
version
- the version which should become live, null to
make the item non-livepublic ContentItem publish(LifecycleDefinition cycleDef, Date startDate)
cycleDef
- The lifecycle definitionstartDate
- The time to schedule the start of the
lifecycle. If null, use the current time as the start date.
public void unpublish()
setLive(null)
.
public Lifecycle getLifecycle()
public boolean isPublished()
public void setLifecycle(Lifecycle lifecycle)
lifecycle
- The lifecyclepublic void removeLifecycle(ContentItem itemToRemove)
public com.arsdigita.categorization.CategoryCollection getCategoryCollection()
public Iterator getCategories(String useContext)
useContext
- the category use context
public void setDefaultCategory(com.arsdigita.categorization.Category category)
category
- The category to set as the default.public void addCategory(com.arsdigita.categorization.Category category)
category
- The category to add this item topublic void removeCategory(com.arsdigita.categorization.Category category)
category
- The category to remove this item frompublic ContentItem copy()
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.
copyServicesFrom(ContentItem)
public final ContentItem copy(ContentItem newParent, boolean copyServices)
NOTE: This method will save the item and all of its unpublished subitems.
newParent
- The new parent item for this itemcopyServices
- Copy services if true
copyServicesFrom(ContentItem)
protected ContentItem makeCopy()
public void copyServicesFrom(ContentItem source)
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.
source
- the ContentItem
whose services will be
copiedcopy()
protected ContentItem createPendingVersion(Lifecycle cycle)
cycle
- the lifecycle to use. A null cycle implies that a live
version should be created.
public void promotePendingVersion(ContentItem pending)
pending
- The pending item to promoteprotected void setVersionRecursively(String version)
version
- The new Version to setpublic ContentItem createLiveVersion()
protected final boolean copyProperty(ContentItem source, String attribute, ItemCopier copier)
copyProperty(CustomCopy, Property, ItemCopier)
instead
ObjectCopier
. ...
ObjectCopier will no longer call it, so existing
implementations need to update to the new signature
public boolean copyProperty(CustomCopy source, com.arsdigita.persistence.metadata.Property property, ItemCopier copier)
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:
Note that for top-level item associations,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; }
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.
copyProperty
in interface CustomCopy
source
- the source CustomCopy itemproperty
- the property to copycopier
- a temporary class that is able to copy a child item
correctly.
public boolean copyServices(ContentItem srcItem)
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.
public String getLanguage()
public void setLanguage(String language)
language
- ISO639 2-letter language codepublic com.arsdigita.globalization.Locale getLocale()
public final void assertDraft()
public final void assertPending()
public final void assertLive()
public final void assertMaster()
protected void beforeDelete()
public com.arsdigita.kernel.User getCreationUser()
getCreationUser
in interface com.arsdigita.auditing.Audited
public Date getCreationDate()
getCreationDate
in interface com.arsdigita.auditing.Audited
public String getCreationIP()
getCreationIP
in interface com.arsdigita.auditing.Audited
public com.arsdigita.kernel.User getLastModifiedUser()
getLastModifiedUser
in interface com.arsdigita.auditing.Audited
public Date getLastModifiedDate()
getLastModifiedDate
in interface com.arsdigita.auditing.Audited
public String getLastModifiedIP()
getLastModifiedIP
in interface com.arsdigita.auditing.Audited
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |