|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface ControllableResource
A proxy for a persistent resource that can be placed under control of a Checkout/Checkin protocol. A controllable resource is always the member of a special type of root folder called a workspace.
The persistent state for a controllable resource may be stored on the client, on the server, or both. Storing the state on the server allows it to be shared by multiple clients. Storing the state on the client provides access to that state even when the client is disconnected from the server, and often provides more efficient access to that state. Note that the choice of what part of the state of a controllable resource is stored on the client is completely up to the implementation. In particular, although most implementations will cache some state on the client, an implementation may chose to store no local state. If some of the persistent state of a resource is stored on both the client and the server, the state on the client and the server must periodically be synchronized. If the state on the server has changed since it was last synchronized with the client, the resource is said to be "stale". If the state on the client has changed since it was last synchronized with the server, the resource is said to be "dirty". Note that the resource can be both dirty and stale.
A server may track the history of a controlled resource, in which case it is called a version-controlled resource.
Nested Class Summary | |
---|---|
static interface |
ControllableResource.Conflict
A version-controlled resource for which new content would have to be created to perform the merge. |
static interface |
ControllableResource.Ignore
A version that would be ignored by the merge because its version history does not appear as a target of the merge. |
static interface |
ControllableResource.MergePreviewReport
A description of how the merge would affect the merge target. |
static interface |
ControllableResource.Update
A version-controlled resource whose CheckedIn property would be updated by the merge. |
Nested classes/interfaces inherited from interface javax.wvcm.Resource |
---|
Resource.GenericResourceImpl |
Method Summary | |
---|---|
void |
doAddLabel(java.lang.String label)
Apply doBind(locVersionByLabel+label, false)
to the CheckedIn version of this ControllableResource , where
locVersionByLabel is the location of the VersionByLabelFolder of the
version history of this version. |
void |
doCheckin()
Apply doCheckin(false, true) |
void |
doCheckin(boolean keepCheckedOut,
boolean forkOK)
Changes the state of the resource identified by this ControllableResource
to be checked-in, and synchronizes the persistent state
of the resource to be that of the persistent state
on the client. |
void |
doCheckout()
Apply doCheckout(true, null, false, false) |
void |
doCheckout(boolean forkOK,
java.util.List activityList,
boolean newActivity,
boolean unreserved)
Checkout this ControllableResource so that its content can be modified. |
void |
doControl()
Require that the resource be checked out to be modified and checked in to commit the modifications. |
void |
doCreateResource()
Create a new persistent resource at the location identified by this ControllableResource . |
void |
doCreateVersionControlledResource(Version v)
Create a new controlled resource at the location identified by the proxy. |
ControllableResource |
doMerge(Version source,
boolean noAutoMerge,
boolean noCheckout,
boolean forkOK,
boolean unreserved,
java.util.List activityList,
boolean newActivity,
PropertyNameList wantedPropertyList)
Merge the version specified in source into the resource
identified by this ControllableResource (the "target"). |
ControllableResource.MergePreviewReport |
doMergePreviewReport(Version source)
Return a MergePreviewReport indicating how the resource identified by this ControllableResource
would be modified by a doMerge . |
Version |
doReadLabelledVersionProperties(java.lang.String label,
PropertyNameList wantedPropertyList)
Apply doReadProperties
to the version selected by label from the version history
of this ControllableResource . |
java.util.Iterator |
doRefresh(PropertyNameList wantedPropertyList,
boolean ignoreDirty)
If both the client and the server are maintaining the persistent state of the resource identified by this ControllableResource ,
synchronizes the state on the client to be that of the server. |
void |
doRemoveLabel(java.lang.String label)
Apply doUnbind(locVersionByLabel+label)
to the CheckedIn version of this ControllableResource , where
locVersionByLabel is the location of the VersionByLabelFolder of the
version history of this version. |
void |
doSetLabel(java.lang.String label)
Apply doBind(locVersionByLabel+label, true)
to the CheckedIn version of this ControllableResource , where
locVersionByLabel is the location of the VersionByLabelFolder of the
version history of this version. |
void |
doUncheckout()
Cancels the checkout of a version-controlled resource, and restores its content to the state of its CheckedOut version. |
java.util.Iterator |
doUpdate(Version v,
PropertyNameList wantedPropertyList)
Update the state of this checked-in version-controlled ControllableResource to be the same as the specified version from
the version history of this ControllableResource . |
java.util.List |
getActivityList()
If this ControllableResource is checked-out,
return a list of Activity objects that identify the
activities that will become the activityList of the version created
when this ControllableResource is checked in; otherwise,
return null / |
java.util.List |
getAutoMergeList()
If this ControllableResource is checked-out,
return a list of Version objects that identify the versions whose
content has been merged by the server into the content of
this ControllableResource ; otherwise, return null . |
Version |
getCheckedIn()
If this ControllableResource is checked-in,
return whether the version whose content
is identical to that of this ControllableResource ;
otherwise, return null . |
Version |
getCheckedOut()
If this ControllableResource is checked-out,
return the value of getCheckedIn
when the checkout was performed; otherwise,
return null . |
Configuration |
getControlledConfiguration()
Return the version-controlled configuration of the baseline-controlled folder of which this ControllableResource is a member. |
PropertyNameList |
getDirtyPropertyList()
Return the list of property values whose persistent state is being maintained on both the client and server, and whose client-side state has changed since the client and server state was last synchronized. |
boolean |
getIsCheckedOut()
Return whether the resource identified by this ControllableResource is
checked-out. |
boolean |
getIsDirtyContent()
Return whether both the client and server are maintaining persistent state for the content of this ControllableResource , and whether the client
content has changed since the client and server content
was last synchronized. |
boolean |
getIsStaleContent()
Return whether both the client and server are maintaining persistent state for the content of this ControllableResource , and whether the server
content has changed since the client and server content
was last synchronized. |
java.util.List |
getMergeList()
If this ControllableResource is checked-out, return
a list of Version objects that identify the versions whose
content must be merged by the client into the content of
this ControllableResource ; otherwise, return null . |
java.util.List |
getPredecessorList()
If this ControllableResource is checked-out,
return a list of Version objects that identify the versions that
will become the predecessors of the version created
when this ControllableResource is checked in;
otherwise, return null . |
ControllableResource |
getServerState()
Return the ControllableResource that identifies the resource
on the server that maintains the state for the client resource
identified by this ControllableResource . |
PropertyNameList |
getStalePropertyList()
Return the list of property values whose persistent state is being maintained on both the client and server, and whose server-side state has changed since the client and server state was last synchronized. |
boolean |
getUnreserved()
Return whether this ControllableResource is checked-out, and whether another checkout of the same version can be made in the same activity as the one in the ActivitySet of this ControllableResource . |
boolean |
getVersionControllable()
Return whether version history will be tracked when the resource is controlled. |
VersionHistory |
getVersionHistory()
Return the version history of the CheckedIn or CheckedOut version. |
Workspace |
getWorkspace()
Return the workspace of which this ControllableResource is a member. |
Resource |
readContent(PropertyNameList wantedPropertyList,
java.io.OutputStream content)
If the resource content is available on the client host, the resource content is written to content
and content is closed. |
Resource |
readProperties(PropertyNameList wantedPropertyList)
Return a Resource containing the wanted properties
that are available on the client host
without communicating with the server. |
void |
setActivityList(java.util.List activityList)
Set the ActivityList property of this ControllableResource . |
void |
setAutoMergeList(java.util.List versionList)
Set the AutoMergeList of this ControllableResource . |
void |
setMergeList(java.util.List versionList)
Set the MergeList of this ControllableResource . |
void |
setPredecessorList(java.util.List versionList)
Specify the versions that will be the predecessors of the version created when this ControllableResource is checked in. |
void |
setUnreserved(boolean val)
Set the value of the Unreserved property of this ControllableResource . |
Method Detail |
---|
void doCreateResource() throws WvcmException
ControllableResource
. The request will
fail if a resource already exists at that location.
WvcmException
- Preconditions:
WvcmException
- Postconditions:
Resource readProperties(PropertyNameList wantedPropertyList) throws WvcmException
Resource
containing the wanted properties
that are available on the client host
without communicating with the server.
wantedPropertyList
- The properties available in the returned proxy.
WvcmException
doReadProperties
Resource readContent(PropertyNameList wantedPropertyList, java.io.OutputStream content) throws WvcmException
content
and content
is closed.
WvcmException
doReadContent
java.util.Iterator doRefresh(PropertyNameList wantedPropertyList, boolean ignoreDirty) throws WvcmException
ControllableResource
,
synchronizes the state on the client to be that of the server.
If this ControllableResource
is a ControllableFolder
, every resource in the configuration
rooted at that folder is refreshed.
wantedPropertyList
- The properties available in the returned proxies.ignoreDirty
- If true, the content should be downloaded even if
it has been changed on the client since the last download from the
server (thereby overwriting those changes). If false, the content should
be downloaded only if it is unchanged since the last download.
ControllableResource
objects
that are dirty or stale
WvcmException
- Preconditions:
WvcmException
- Postconditions:
void doControl() throws WvcmException
WvcmException
- Preconditions:
WvcmException
- Postconditions:
void doCheckout() throws WvcmException
doCheckout(true, null, false, false)
WvcmException
void doCheckin() throws WvcmException
doCheckin(false, true)
WvcmException
Workspace getWorkspace() throws WvcmException
ControllableResource
is a member.
By definition, the workspace property of a workspace
identifies itself, and the workspace property of any other
type of resource must identify the same workspace as its parent.
WvcmException
- if this ControllableResource
was not created with
WORKSPACE
as a wanted property.boolean getIsCheckedOut() throws WvcmException
ControllableResource
is
checked-out.
WvcmException
- if this ControllableResource
was not created with
IS_CHECKED_OUT
as a wanted property.ControllableResource getServerState() throws WvcmException
ControllableResource
that identifies the resource
on the server that maintains the state for the client resource
identified by this ControllableResource
. If this Controllable
resource only has state on the server or only has state on the client,
null
is returned.
WvcmException
- if this ControllableResource
was not created with
SERVER_STATE
as a wanted property.Workspace.setServerState(javax.wvcm.Workspace)
boolean getIsStaleContent() throws WvcmException
ControllableResource
, and whether the server
content has changed since the client and server content
was last synchronized.
WvcmException
- if this ControllableResource
was not created with
IS_STALE_CONTENT
as a wanted property.boolean getIsDirtyContent() throws WvcmException
ControllableResource
, and whether the client
content has changed since the client and server content
was last synchronized.
WvcmException
- if this ControllableResource
was not created with
IS_DIRTY_CONTENT
as a wanted property.PropertyNameList getStalePropertyList() throws WvcmException
WvcmException
- if this ControllableResource
was not created with
STALE_PROPERTY_LIST
as a wanted property.PropertyNameList getDirtyPropertyList() throws WvcmException
WvcmException
- if this ControllableResource
was not created with
DIRTY_PROPERTY_LIST
as a wanted property.void doCreateVersionControlledResource(Version v) throws WvcmException
v
- The version used to initialize the controlled
resource.
WvcmException
- Preconditions:
WvcmException
- Postconditions:
void doCheckin(boolean keepCheckedOut, boolean forkOK) throws WvcmException
ControllableResource
to be checked-in, and synchronizes the persistent state
of the resource to be that of the persistent state
on the client. If version history is being tracked for the
resource, the current content of the resource is captured
in a new version resource at a server-defined location.
A doCheckin request can be applied to a checked-out version-controlled configuration
to produce a new baseline whose Baseline-Folder captures the current state
of the version-controlled members of the RootFolder of the configuration.
keepCheckedOut
- indicates whether to checkout the
resource again immediately after checking it in.
If keepCheckedOut is true
, the ActivityList
and Unreserved properties should not be changed by the checkout.forkOK
- indicates whether to fork even if forking
is discouraged.
WvcmException
- Preconditions:
WvcmException
- Postconditions:
void doCheckout(boolean forkOK, java.util.List activityList, boolean newActivity, boolean unreserved) throws WvcmException
ControllableResource
so that its content can be modified.
forkOK
- Indicates whether to do the checkout even if the
version already has a successor or a checkout.activityList
- A list of Activity
objects that identify
the activities to which the work on the
checked-out resource will contribute.newActivity
- Indicates whether to create a new activity
for the checkout.unreserved
- Indicates whether to do the checkout even
if there already is a checkout from the currently selected
version in one of the activities specified in the activityList.
WvcmException
- Preconditions:
WvcmException
- Postconditions:
ControllableResource doMerge(Version source, boolean noAutoMerge, boolean noCheckout, boolean forkOK, boolean unreserved, java.util.List activityList, boolean newActivity, PropertyNameList wantedPropertyList) throws WvcmException
source
into the resource
identified by this ControllableResource
(the "target").
If the target is checked-in, and the source version is a descendant
of the target version, the target is updated to the source version.
If the target is checked-in, and the source version is an ancestor
of the target version, the target is left unmodified.
If the target is checked-out, or if the target version is on a different
line of descent than the source version, the target is checked out
(if it is not already checked-out), and the source version is either
added to the MergeList or the AutoMergeList of the target.
If a source version is added to the AutoMergeList, the server must
have updated the content of the target to contain the results of merging
the content of the source version with the content of the target at the
time of the merge.
source
- The version to be merged.noAutoMerge
- The server is not allowed to auto-merge.noCheckout
- The server is not allowed to checkout files for merging.forkOK
- Passed into any checkout requests.unreserved
- Passed into any checkout requests.activityList
- Passed into any checkout requests.newActivity
- Passed into any checkout requests.wantedPropertyList
- The properties available in the returned proxy.
ControllableResource
that contains the requested properties
of the resource modified by the merge.
WvcmException
- Preconditions:
WvcmException
- Postconditions:
ControllableResource.MergePreviewReport doMergePreviewReport(Version source) throws WvcmException
ControllableResource
would be modified by a doMerge
.
source
- The version to be merged.
WvcmException
void doUncheckout() throws WvcmException
WvcmException
- Preconditions:
WvcmException
- Postconditions:
java.util.Iterator doUpdate(Version v, PropertyNameList wantedPropertyList) throws WvcmException
ControllableResource
to be the same as the specified version from
the version history of this ControllableResource
.
v
- The version specifying the new state of the resource
identified by this ControllableResource
.wantedPropertyList
- The list of properties that will be available
on each ControllableResource
in the result.
ControllableResource
objects that
have been modified as a result of the doUpdate request.
Each version-controlled resource contains a value for each
of the properties specified in the WantedPropertyList.
WvcmException
- Preconditions:
WvcmException
- Postconditions:
void doAddLabel(java.lang.String label) throws WvcmException
doBind(locVersionByLabel+label, false)
to the CheckedIn version of this ControllableResource
, where
locVersionByLabel is the location of the VersionByLabelFolder of the
version history of this version.
WvcmException
void doRemoveLabel(java.lang.String label) throws WvcmException
doUnbind(locVersionByLabel+label)
to the CheckedIn version of this ControllableResource
, where
locVersionByLabel is the location of the VersionByLabelFolder of the
version history of this version.
WvcmException
void doSetLabel(java.lang.String label) throws WvcmException
doBind(locVersionByLabel+label, true)
to the CheckedIn version of this ControllableResource
, where
locVersionByLabel is the location of the VersionByLabelFolder of the
version history of this version.
WvcmException
Version doReadLabelledVersionProperties(java.lang.String label, PropertyNameList wantedPropertyList) throws WvcmException
doReadProperties
to the version selected by label
from the version history
of this ControllableResource
.
WvcmException
boolean getVersionControllable() throws WvcmException
WvcmException
- if this ControllableResource
was not created with
VERSION_CONTROLLABLE
as a wanted property.doControl
VersionHistory getVersionHistory() throws WvcmException
WvcmException
- if this ControllableResource
was not created with
VERSION_HISTORY
as a wanted property.Configuration getControlledConfiguration() throws WvcmException
ControllableResource
is a member.
WvcmException
- if this ControllableResource
was not created with
VERSION_CONTROLLED_CONFIGURATION
as a wanted property.Version getCheckedIn() throws WvcmException
ControllableResource
is checked-in,
return whether the version whose content
is identical to that of this ControllableResource
;
otherwise, return null
.
WvcmException
- if this ControllableResource
was not created with
CHECKED_IN
as a wanted property.Version getCheckedOut() throws WvcmException
ControllableResource
is checked-out,
return the value of getCheckedIn
when the checkout was performed; otherwise,
return null
.
WvcmException
- if this ControllableResource
was not created with
CHECKED_OUT
as a wanted property.java.util.List getPredecessorList() throws WvcmException
ControllableResource
is checked-out,
return a list of Version
objects that identify the versions that
will become the predecessors of the version created
when this ControllableResource
is checked in;
otherwise, return null
.
WvcmException
- if this ControllableResource
was not created with
PREDECESSOR_LIST
as a wanted property.void setPredecessorList(java.util.List versionList)
ControllableResource
is checked in.
versionList
- A list of Version
objects that will
be the predecessors of the version created when this ControllableResource
is checked in.java.util.List getActivityList() throws WvcmException
ControllableResource
is checked-out,
return a list of Activity
objects that identify the
activities that will become the activityList of the version created
when this ControllableResource
is checked in; otherwise,
return null
/
WvcmException
- if this ControllableResource
was not created with
ACTIVITY_LIST
as a wanted property.void setActivityList(java.util.List activityList)
ControllableResource
.
activityList
- A list of Activity
objects that identify
the new value for the ActivityList property.boolean getUnreserved() throws WvcmException
ControllableResource
.
WvcmException
- if this ControllableResource
was not created with
UNRESERVED
as a wanted property.void setUnreserved(boolean val)
ControllableResource
.
val
- The new value for the Unreserved property of this ControllableResource
.java.util.List getMergeList() throws WvcmException
ControllableResource
is checked-out, return
a list of Version
objects that identify the versions whose
content must be merged by the client into the content of
this ControllableResource
; otherwise, return null
.
WvcmException
- if this ControllableResource
was not created with
MERGE_LIST
as a wanted property.void setMergeList(java.util.List versionList)
ControllableResource
.
In particular, a client is responsible for deleting versions from
the MergeList after the user has verified that the current
content represents a correct merge of that version.
versionList
- A list of Version
objects that will be
the value of the MergeList property.java.util.List getAutoMergeList() throws WvcmException
ControllableResource
is checked-out,
return a list of Version
objects that identify the versions whose
content has been merged by the server into the content of
this ControllableResource
; otherwise, return null
.
WvcmException
- if this ControllableResource
was not created with
AUTO_MERGE_LIST
as a wanted property.void setAutoMergeList(java.util.List versionList)
ControllableResource
.
A client is responsible for deleting entries from
the AutoMergeList after the user has verified that the automatic
merge was performed correctly by the server.
versionList
- A list of Version
objects that identify
the new value for the AutoMergeList property.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |