001: /*
002: * Copyright 2004 Outerthought bvba and Schaubroeck nv
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.outerj.daisy.repository;
017:
018: import org.outerx.daisy.x10.VersionDocument;
019:
020: import java.util.Date;
021:
022: /**
023: * A version of a {@link Document}.
024: *
025: * <p>This object provides access to the all versioned information of a document,
026: * for a specific version of the document. Versions cannot be modified (except
027: * their state, see below),
028: * they are read-only. See {@link Document#save()} for when a version is created.
029: *
030: * <p>A version can have a state of either 'publish' or 'draft'. This state
031: * can be changed at any time.
032: */
033: public interface Version extends VersionedData {
034: /**
035: * The id of the version, which is a sequence number, the first version
036: * being 1, then 2, and so on.
037: */
038: long getId();
039:
040: /**
041: * Returns the date when this version was created.
042: */
043: Date getCreated();
044:
045: /**
046: * Returns the id of the user that created this version. You can
047: * retrieve full information on the user via the {@link org.outerj.daisy.repository.user.UserManager}.
048: */
049: long getCreator();
050:
051: /**
052: * Get an XML document containing information about this version, but without
053: * the actual versioned content, thus no fields, parts, links etc. This is
054: * useful when retrieving an overview of all versions of a document.
055: */
056: VersionDocument getShallowXml();
057:
058: /**
059: * Get an XML document describing the version.
060: */
061: VersionDocument getXml() throws RepositoryException;
062:
063: /**
064: * Changes the state of this version.
065: *
066: * <p>Sinced daisy 2.2, this method no longer has immediate effect, you need to call version.save() to make the change permanent.</p>
067: */
068: void setState(VersionState state);
069:
070: /**
071: * Returns the current state of this version. This is the state as it
072: * was when this version object was loaded, it may have changed in the
073: * meantime.
074: */
075: VersionState getState();
076:
077: /**
078: * Changes the 'synced with' field for this version. The purpose of this field is for
079: * translation management, it indicates that the data in this version is translated
080: * content which is up to date with a certain version of some other (reference) language.
081: *
082: * <p>This method does not have immediate effect. You need to call version.save() to make the change permanent.</p>
083: *
084: * <p>To clear the 'synced with' field, specify -1 for languageId and versionId.
085: *
086: * @throws IllegalArgumentException if exactly one of languageId and versionId is -1 or versionId < 0
087: * @throws RepositoryException if the languageId!=-1 and the language does not exist
088: * @since daisy 2.2
089: */
090: void setSyncedWith(long languageId, long versionId)
091: throws RepositoryException;
092:
093: /**
094: * Sets the 'synced with' pointer by specifying a VersionKey object.
095: * Only the language ID and version ID fields of the VersionKey object
096: * are significant. The syncedWith argument can be null.
097: */
098: void setSyncedWith(VersionKey syncedWith)
099: throws RepositoryException;
100:
101: /**
102: * Returns a VersionKey that identifies the version that this version was synced to.
103: * Returns null if not set.
104: */
105: VersionKey getSyncedWith();
106:
107: /**
108: * Changes the change type for this version.
109: *
110: * <p>This method does not have immediate effect. You need to call version.save() to make the change permanent.</p>
111: *
112: * <p>The change type indicates if the version contains major or minor changes.
113: *
114: * <p>When using translation management, the change type is used to indicate that
115: * a version contains changes which render translations invalid. So if a user
116: * makes changes to a version, even though these might seem minor, but which
117: * should be replicated in translations, than the change type should be set
118: * to major (when using translation management, otherwise you can assign
119: * your own meaning to this field).
120: *
121: * @since daisy 2.2
122: */
123: void setChangeType(ChangeType changeType)
124: throws RepositoryException;
125:
126: /**
127: * Returns the change type for this version (never null).
128: */
129: ChangeType getChangeType();
130:
131: /**
132: * Changes the change comment for this version.
133: *
134: * <p>This method does not have immediate effect. You need to call version.save() to make the change permanent.</p>
135: *
136: * @param changeComment the comment text, can be null to clear the change comment
137: */
138: void setChangeComment(String changeComment)
139: throws RepositoryException;
140:
141: /**
142: * Returns the change comment for this version (can be null).
143: */
144: String getChangeComment();
145:
146: /**
147: * Saves changes made to the metadata of this version (versionState, syncedWith, changeType and changeComment).
148: */
149: void save() throws RepositoryException;
150:
151: /**
152: * Get the id of the user that last changed the state of this version.
153: */
154: long getLastModifier();
155:
156: /**
157: * Get the time at which the state of this version was last changed.
158: */
159: Date getLastModified();
160:
161: /**
162: * Get the sum of the size of the parts in this version.
163: */
164: long getTotalSizeOfParts();
165: }
|