public interface RepositoryService
A repository file is typically modified by checking it out into a user's workspace, modifying the file in the workspace, and then checking the modified files into the repository.
The repository file can be versioned or unversioned.
When an unversioned file is updated, its contents are replaced by the new content. When a versioned file is updated,
a new version of the file is created with the new version number that is specified by a
RepositoryCheckinSpecification
. The RepositoryCheckinSpecification indicates that the major or minor number
field is incremented or specifies the exact version label to use for the update. New version labels must always be an
increase of the previous label.
Modifier and Type | Method and Description |
---|---|
RepositoryFile |
checkin(String path,
RepositoryCheckinSpecification checkinSpecification)
Checks in the contents of the file from the current user's workspace to the repository.
|
RepositoryFile |
checkout(String path)
Checks out the file from the repository.
|
void |
clearCheckedOutFilesSearchResults()
Releases any cached information about the query that is associated with the current search.
|
RepositoryItem |
copy(String sourcePath,
String destinationPath)
Copies the repository object from the source path to the destination path.
|
void |
copyLatestFileVersionToWorkspace(String path)
Copies the latest version of the repository file to your workspace.
|
void |
copySpecificFileVersionToWorkspace(String path,
String version)
Copies the version of the repository file to your workspace.
|
RepositoryContext |
createContext(String path,
String typeId)
Creates a context at the specified location in the repository.
|
RepositoryFile |
createFile(String path,
String localFilePath,
String comment,
boolean createParentFolders)
Creates an unversioned file in the repository.
|
RepositoryFolder |
createFolder(String path,
boolean createParentFolders)
Creates a folder at the specified location in the repository.
|
RepositoryFile |
createVersionedFile(String path,
String localFilePath,
String comment,
String startingVersion,
boolean createParentFolders)
Creates a versioned file in the repository.
|
List<String> |
delete(String path)
Logically deletes the object (moved to the recycle bin).
|
RepositoryFile |
disableVersioning(String path,
String comment)
Disables versioning support for the repository file.
|
void |
downloadFile(String path,
String version,
String outputFilePath)
Downloads the current contents of the file to a local file.
|
RepositoryFile |
enableVersioning(String path,
String startingVersion,
String comment)
Enables versioning support for the repository file.
|
boolean |
exists(String path)
Indicates whether the path exists in the repository.
|
List<SynchronizationInfo> |
getCheckedOutFilesSearchResults(int fromRow,
int toRow)
Retrieves a range of results after calling
searchCheckedOutFiles(CheckedOutFilesQuery) . |
List<RepositoryItem> |
getChildren(String path)
Gets the children of the container path.
|
List<RepositoryItem> |
getChildrenByType(String path,
String typeId)
Gets the children of the container path.
|
RepositoryContext |
getContext(String path)
Gets the repository context at the path.
|
RepositoryContext |
getContextById(String id)
Gets the repository context by its unique identifier.
|
RepositoryFile |
getFile(String path)
Gets the repository file at the path.
|
RepositoryFile |
getFileVersion(String path,
String version)
Gets the specific version of a versioned file.
|
List<RepositoryFileVersionInfo> |
getFileVersionInfos(String path)
Gets the list of the version information that represents each version of the repository file.
|
List<RepositoryFile> |
getFileVersions(String path)
Gets the entire list of versions of the file.
|
RepositoryFolder |
getFolder(String path)
Gets the repository folder at the path.
|
RepositoryItem |
getItem(String path)
Gets the repository object at the path.
|
int |
getPageSizeLimit()
Gets the maximum number of checked out files that can be returned in a single request.
|
RepositoryContext |
getParentMembershipContext(String path)
Gets the nearest parent context with membership capability for the repository path.
|
RepositoryContext |
getTopLevelContextByName(String name)
Gets a top-level context by name.
|
List<RepositoryContext> |
getTopLevelContexts()
Gets the list of all of the accessible top-level contexts.
|
RepositoryFile |
lockFile(String path)
Locks the specified repository file.
|
RepositoryItem |
move(String sourcePath,
String destinationPath)
Moves the repository object from the source path to the destination path.
|
List<String> |
permanentlyDelete(String path)
Permanently deletes the specified object.
|
RepositoryItem |
rename(String path,
String name)
Renames the repository object.
|
RepositorySearchResults |
search(SearchQuery query)
Searches the repository based on the specified query.
|
SearchResultsInfo |
searchCheckedOutFiles(CheckedOutFilesQuery query)
Searches the checked out files information and returns the information that describes the results, not the
results themselves.
|
List<RepositoryStateChangeResult> |
setState(String path,
RepositoryItem.State state,
String comment,
boolean recurse)
Sets the state of a repository context.
|
RepositoryFile |
undoCheckout(String path)
Undoes the checkout of the file.
|
RepositoryFile |
unlockFile(String path)
Unlocks the repository file.
|
RepositoryFile |
updateFileContents(String path,
RepositoryCheckinSpecification checkinSpecification,
String localFileLocation)
Updates the contents of a repository file with the provided content or creates a new version of the file, if the
file is versioned.
|
RepositoryItem |
updateItem(RepositoryItem item)
Updates the editable attributes on a repository object.
|
RepositoryContext createContext(String path, String typeId) throws RepositoryItemNotFoundException, RepositoryItemExistsException
path
- the path of the context to create.typeId
- the type of context to create.RepositoryItemNotFoundException
- thrown when a parent context does NOT exist.RepositoryItemExistsException
- thrown when an object exists in the repository at the specified path.RepositoryFolder createFolder(String path, boolean createParentFolders) throws RepositoryItemNotFoundException, RepositoryItemExistsException
path
- the path of the folder to create.createParentFolders
- parent folders should be automatically created during the operation. This does NOT
include creating contexts, only folders.RepositoryItemNotFoundException
- thrown when createParentContainers
is set to false
and a
parent container does NOT exist.RepositoryItemExistsException
- thrown when an object exists in the repository at the specified path.RepositoryFile createFile(String path, String localFilePath, String comment, boolean createParentFolders) throws RepositoryItemNotFoundException, RepositoryItemExistsException, IOException
path
- the path of the unversioned file to create.localFilePath
- the local file path with the contents for the new repository file.comment
- (optional) the comment about the unversioned file.createParentFolders
- missing parent containers should be automatically created during the operation. This
does NOT include creating contexts, only folders.RepositoryItemNotFoundException
- thrown when createParentContainers
is set to false
and a
parent container does NOT exist.RepositoryItemExistsException
- thrown when an object exists at the specified path.IOException
- thrown when there is a problem streaming the file contents.RepositoryFile createVersionedFile(String path, String localFilePath, String comment, String startingVersion, boolean createParentFolders) throws RepositoryItemNotFoundException, RepositoryItemExistsException, IOException
path
- the path of the versioned file to create.localFilePath
- the local file path with the contents for the new repository file.comment
- (optional) the comment about the versioned file.startingVersion
- (optional) the version to use for the initial version of the repository file. The default
version of 1.0
is used if not provided.createParentFolders
- missing parent containers should be automatically created during the operation. This
does NOT include creating contexts, only folders.RepositoryItemNotFoundException
- thrown if createParentFolders
was false
and a parent
container does NOT exist.RepositoryItemExistsException
- thrown when an object exists at the specified path.IOException
- thrown when there is a problem streaming the file contents.RepositoryItem updateItem(RepositoryItem item) throws RepositoryItemNotFoundException
The expected flow for the call is to first retrieve the object by calling getItem(String)
or
getChildren(String)
, make any required updates to the editable attributes, and then call this method to
persist the changes.
item
- the repository object to update.RepositoryItemNotFoundException
- thrown when repository object was not found at the given path.RepositoryItem rename(String path, String name) throws RepositoryItemNotFoundException, RepositoryItemExistsException
path
- the path of the repository object to rename.name
- the new nameRepositoryItemNotFoundException
- thrown when repository object was not found at the given path.RepositoryItemExistsException
- thrown when a repository object exists in the same location with the new
name.RepositoryItem move(String sourcePath, String destinationPath) throws RepositoryItemNotFoundException, RepositoryItemExistsException, RepositoryItemMoveException
Only folders and files can be moved. Objects that are moved maintain their identifiers and their audit trail.
sourcePath
- the path of the file or folder to move.destinationPath
- the path of the destination file or folder to move to, which includes the name of the
item.RepositoryItemNotFoundException
- thrown when the specified source path or destination location cannot be
found.RepositoryItemExistsException
- thrown when an object exists at the destination path.RepositoryItemMoveException
- thrown when the move request was not possible.RepositoryItem copy(String sourcePath, String destinationPath) throws RepositoryItemNotFoundException, RepositoryItemExistsException, RepositoryItemCopyException
Only folders and files can be copied. Items that are copied create new items, with new identifiers. If a folder is copied, the folder and all readable contents within it are copied as well. If a versioned file is copied, only the latest version of the file is copied.
sourcePath
- the path of the file or folder to copy.destinationPath
- the path of the destination file or folder to create, which includes the name of the
created copy.RepositoryItemNotFoundException
- thrown when the specified source path or destination location cannot be
found.RepositoryItemExistsException
- thrown when an object exists at the destination path.RepositoryItemCopyException
- thrown when the copy request is not possible, for example, the destination
path was a child of the source path.List<String> delete(String path) throws RepositoryItemNotFoundException, RepositoryItemDeleteException
path
- the object to logically delete.RepositoryItemNotFoundException
- thrown when repository object was not found at the given path.RepositoryItemDeleteException
- thrown when there was an issue logically deleting the object.List<String> permanentlyDelete(String path) throws RepositoryItemNotFoundException, RepositoryItemDeleteException
path
- the object to permanently delete.RepositoryItemNotFoundException
- thrown when repository object was not found at the given path.RepositoryItemDeleteException
- thrown when there was an issue permanently deleting the item.RepositoryFile enableVersioning(String path, String startingVersion, String comment) throws RepositoryItemNotFoundException, RepositoryItemVersioningException
path
- the repository file to version.startingVersion
- (optional) the version to use for the initial version of the repository file. The default
version of 1.0
is used if not provided.comment
- (optional) a comment that describes the version.RepositoryItemNotFoundException
- thrown when repository object was not found at the given path.RepositoryItemVersioningException
- thrown when the file versioning could not be enabled, such as when the
file already versioned.RepositoryFile disableVersioning(String path, String comment) throws RepositoryItemNotFoundException, RepositoryItemVersioningException
path
- the repository file to unversion.comment
- (optional) a comment that describes the file's contents.RepositoryItemNotFoundException
- thrown when the specified path cannot be found.RepositoryItemVersioningException
- thrown when versioning could not be disabled for the file, such as when
the file is already unversioned.RepositoryFile lockFile(String path) throws RepositoryItemNotFoundException, RepositoryItemLockException
path
- the path of the repository file to lock.RepositoryItemNotFoundException
- thrown when the specified path cannot be found.RepositoryItemLockException
- thrown when the specified file could not be locked, such as when the file is
already locked.RepositoryFile unlockFile(String path) throws RepositoryItemNotFoundException, RepositoryItemUnlockException
path
- the path of the repository file to unlock.RepositoryItemNotFoundException
- thrown when the specified path cannot be found.RepositoryItemUnlockException
- thrown when the specified file could not be unlocked, such as when the file
is already unlocked.boolean exists(String path)
path
- the path of the repository item.True
if the path exists, false
otherwise.RepositoryItem getItem(String path) throws RepositoryItemNotFoundException
path
- the path of the repository item.RepositoryItemNotFoundException
- thrown when repository object was not found at the given path.RepositoryContext getTopLevelContextByName(String name) throws RepositoryItemNotFoundException
name
- the name of the top-level context.RepositoryItemNotFoundException
- thrown if a top-level context was not found with the specified name.List<RepositoryContext> getTopLevelContexts()
RepositoryContext getContext(String path) throws RepositoryItemNotFoundException
path
- the path of the repository context.RepositoryItemNotFoundException
- thrown when a repository context was not found at the given path.RepositoryContext getContextById(String id) throws RepositoryItemNotFoundException
id
- the identifier of the repository context.RepositoryItemNotFoundException
- thrown when a repository context was not found with the specified
identifier.RepositoryContext getParentMembershipContext(String path) throws RepositoryItemNotFoundException, MembershipContextNotFoundException
path
- the repository path for which the nearest membership context is found. This can be a folder path,
file path, context path, or any other repository type in the system.RepositoryItemNotFoundException
- thrown when the repository item was not found at the given path.MembershipContextNotFoundException
- thrown when the repository item has no parent context with membership
capability. This is thrown when a top repository context path is specified.RepositoryFolder getFolder(String path) throws RepositoryItemNotFoundException
path
- the path of the repository folder.RepositoryItemNotFoundException
- thrown when the repository folder was not found at the given path.RepositoryFile getFile(String path) throws RepositoryItemNotFoundException
path
- the path of the repository file.RepositoryItemNotFoundException
- thrown when the repository file was not found at the given path.List<RepositoryItem> getChildren(String path) throws RepositoryItemNotFoundException
path
- the path of the parent container.RepositoryItemNotFoundException
- thrown when the repository item was not found at the given path.List<RepositoryItem> getChildrenByType(String path, String typeId) throws RepositoryItemNotFoundException
path
- the path of the parent container.typeId
- the type of children to return.RepositoryItemNotFoundException
- thrown when the repository item was not found at the given path.RepositoryFile getFileVersion(String path, String version) throws RepositoryItemNotFoundException
path
- the path of the versioned file.version
- the desired version of the file.RepositoryItemNotFoundException
- thrown when the repository item was not found at the given path, if it
was not a versioned file, or if the specified version does not exist for that versioned file.List<RepositoryFile> getFileVersions(String path) throws RepositoryItemNotFoundException, RepositoryItemVersioningException
path
- the path of the file.RepositoryItemNotFoundException
- thrown when the repository item was not found at the given path.RepositoryItemVersioningException
- thrown when the file at the specified path is not versioned.List<RepositoryFileVersionInfo> getFileVersionInfos(String path) throws RepositoryItemNotFoundException, RepositoryItemVersioningException
path
- The repository file.RepositoryItemNotFoundException
- thrown when the repository item was not found at the given path.RepositoryItemVersioningException
- thrown when the file at the specified path is not versioned.void downloadFile(String path, String version, String outputFilePath) throws RepositoryItemNotFoundException, IOException
Note: This action has no effect upon the workspace. The file is downloaded directly to the client computer.
path
- the path of the repository file to download.version
- (optional) the version of the file to download, blank if the file is unversioned, or you want the
latest version.outputFilePath
- the location on the client computer in which to store the file contents.RepositoryItemNotFoundException
- thrown when the repository item was not found at the given path.IOException
- thrown when there was a problem streaming the file contents.RepositoryFile updateFileContents(String path, RepositoryCheckinSpecification checkinSpecification, String localFileLocation) throws RepositoryItemNotFoundException, RepositoryItemVersioningException, RepositoryItemCheckoutException, IOException
Note: This method allows the direct updating of a repository file without going through the typical checkout/checkin process, and therefore, has no effect on your workspace contents.
If null
is specified for the checkin specification, that is interpreted as a blank comment and
MAJOR
version update value if the file is versioned.
path
- the repository file to update.checkinSpecification
- how the file version number should be modified (if the file is versioned).localFileLocation
- the local file path with the contents of the new version of the file.RepositoryItemNotFoundException
- thrown when the repository item was not found at the given path.RepositoryItemVersioningException
- thrown when the version specification was not valid or inappropriate
for the specified file.RepositoryItemCheckoutException
- thrown when the specified file specified is currently checked out.IOException
- thrown when there was a problem streaming the file contents.List<RepositoryStateChangeResult> setState(String path, RepositoryItem.State state, String comment, boolean recurse) throws RepositoryItemNotFoundException
RepositoryItem.State
s allowed:
Setting the state requires the privilege
PRIVILEGE_MANAGE_STATE
. In
addition, READ METADATA
and WRITE METADATA
permissions are required on the context. If the user
setting the state has these authorizations, then they are allowed to set the state on all descendents implicitly.
Even if they are lacking one or both of the permissions required on the context to be set, the state IS
set implicitly, if the state is cascading.
As described above, having an ACTIVE context within a CLOSED context is an invalid state. Therefore, when setting a context from CLOSED to ACTIVE and the parent context is CLOSED, this action automatically changes the state of all immediate ancestors that are CLOSED to ACTIVE.
path
- the path to the context where state is to be set.state
- the state to set the context.comment
- (optional) comment that is used in the audit record. If no comment is provided then that value
will not be audited. The comment is not persisted in any other place except the audit trail.recurse
- the state to be set should cascade to all descendent contexts. All non-context descendents
(including non-stateable) contexts are always set whether this flag is set or not. If a context is set
to ACTIVE, all folders, files and non-stateable context descendents are set to the context
state automatically by default. This flag determines whether stateable context descendents should have
their state changed as well. This flag is used only when setting the state to ACTIVE. When
setting a context state to CLOSED, then ALL descendents MUST be set to CLOSED
because ACTIVE content within a CLOSED context is an invalid state. Therefore, when
closing a context, this flag is ignored because recursion is a requirement.RepositoryItemNotFoundException
- thrown when the item no longer exists.IllegalTypeException
- thrown if the path specified is for a type that is not Stateable
. This
includes non-stateable context types as well as folders and files.PrivilegeRequiredAccessDeniedException
- thrown when the current user does not have the scoped privilege
PRIVILEGE_MANAGE_STATE
granted at the context to be set or higher. This can also be thrown if the
user is trickling the state change upwards and they do NOT have the privilege on a parent.PermissionRequiredAccessDeniedException
- thrown when the current user does not have READ
and
WRITE METADATA
permissions on the context to be set. This can also be thrown when the user is
trickling the state change upwards and they do NOT have the permissions on a parent.RepositoryFile checkout(String path) throws RepositoryItemNotFoundException, RepositoryItemCheckoutException
path
- the repository file to check out.RepositoryItemNotFoundException
- thrown when the specified path cannot be found.RepositoryItemCheckoutException
- thrown when the file is already checked out or locked.RepositoryFile undoCheckout(String path) throws RepositoryItemNotFoundException, RepositoryItemUndoCheckoutException
path
- the repository file to release.RepositoryItemNotFoundException
- thrown when the specified path cannot be found.RepositoryItemUndoCheckoutException
- thrown when the repository file was not checked out.RepositoryFile checkin(String path, RepositoryCheckinSpecification checkinSpecification) throws RepositoryItemNotFoundException, RepositoryItemCheckinException
path
- the file to check into the repository.checkinSpecification
- how the new version should be labeled. If null
is specified for
checkinSpecification, that is interpreted as a blank comment (and MINOR version update value if the
file is versioned).RepositoryItemNotFoundException
- thrown when the specified path cannot be found.RepositoryItemCheckinException
- thrown when the specified file was not checked out.void copyLatestFileVersionToWorkspace(String path) throws RepositoryItemNotFoundException
path
- the path of the repository file.RepositoryItemNotFoundException
- repository file was not found at the given path.void copySpecificFileVersionToWorkspace(String path, String version) throws RepositoryItemNotFoundException
path
- the path of the repository file.version
- The specific version that should be brought into your workspace.RepositoryItemNotFoundException
- repository file was not found at the given path.SearchResultsInfo searchCheckedOutFiles(CheckedOutFilesQuery query)
getCheckedOutFilesSearchResults(int, int)
. When the results are no longer
required, call clearCheckedOutFilesSearchResults()
to release any server-side resources related with the
query.
Note: Only one query can be active at a time for each client. The results generated for the query can be used to
iterate through the results by calling getCheckedOutFilesSearchResults(int, int)
, but if the same client
calls this method again, a new set of results are generated and the previous results are no longer valid.
query
- CheckedOutFilesQuery contains the search criteria with which to query the checked out files. Passing
null returns the current user's checked out files.RepositorySearchResults search(SearchQuery query) throws RepositorySearchException
RepositoryItem
s
that satisfy the query. However, items in the recycle bin and any items that the current user does not have read
access to will not be returned. If the server cannot process all of the items due to server limitations,
RepositorySearchResults.isLimitReached()
will be set to true
. If true, more items may exist that
satisfy the query but they could not be returned.
Search rules:
To search file content, setTypeId must be called with one of the following types. Note because job files contain XML content, search will only find what is in attribute values.
query
- contains the search criteria with which to query the repository. Must have a value for at least one
query field.RepositoryItem
s that satisfy the query and whether the limit was reached on the server.RepositorySearchException
- thrown if there was an issue processing the repository searchList<SynchronizationInfo> getCheckedOutFilesSearchResults(int fromRow, int toRow) throws CheckedOutFilesSearchException
searchCheckedOutFiles(CheckedOutFilesQuery)
. The
from row
and to row
values should be between 1 and the total number of rows retrieved by the
query. This is considered a page
of results and therefore a pageable
results model.
Note: The maximum number of records that can be returned for a single page is determined by
getPageSizeLimit()
. The default maximum is 5000.
fromRow
- the starting row number in which to include in the results. Must be greater than 0.toRow
- the ending row number to include in the results. Must be less than or equal to the total row count
and the total number retrieved must be less than or equal to the page size limit.CheckedOutFilesSearchException
- thrown when the total row number requested exceeds the page size limit.void clearCheckedOutFilesSearchResults()
finally
block for each call to searchCheckedOutFiles(CheckedOutFilesQuery)
. If the
results no longer exist when this method is called, then this method returns without any further action.int getPageSizeLimit()
Copyright (c) 2020, SAS Institute Inc., Cary, NC, USA