com.sas.hls.resource.repository
Interface RepositoryResourceService


public interface RepositoryResourceService

A service for manipulating resources in the repository.

Repository files are typically modified by checking them out into a user's workspace, modifying the file in the workspace, and then when the user is satisfied with the modifications the updated file is checked back into the repository.

Repository files can be either 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 that resource is created with its new version number specified by a ResourceCheckinSpecification. The ResourceCheckinSpecification indicates that the major or minor number field should be incremented or specifies the exact version label to be used for this update. New version labels must always be an increase of the previous label.


Method Summary
 void checkinFileFromWorkspace(String path, ResourceCheckinSpecification checkinSpecification)
          Check in the contents of this resource from the current user's workspace to the repository.
 void checkoutFileToWorkspace(String path)
          Checkout the specified resource from the repository and into the current user's workspace.
 void checkoutFileToWorkspaceAndDownload(String path, String localFilePath)
          Checkout the specified resource from the repository to the current user's workspace, and then download the content of the workspace file to the specified local file path.
 RepositoryResource copy(String sourcePath, String destinationPath)
          Copy the file or folder from the source path to the destination path.
 RepositoryFile createFile(String path, String localFilePath, String comment, boolean createParentFolders)
          Create an unversioned file in the repository.
 RepositoryFolder createFolder(String path, boolean createParentFolder)
          Create a container at the given location in the repository.
 RepositoryFile createVersionedFile(String path, String localFilePath, String comment, String startingVersion, boolean createParentFolders)
          Create a versioned file in the repository.
 void delete(String path)
          Logically delete the specified resource (i.e.
 RepositoryFile disableVersioningOnFile(String path, String comment)
          Disable versioning support for the specified RepositoryFile.
 void downloadFile(String path, String version, String outputFilePath)
          Download the current contents of a specified ServerResource to the specified local file.
 RepositoryFile enableVersioningOnFile(String path, String comment, String startingVersion)
          Turn on versioning support for the specified RepositoryFile.
 boolean exists(String path)
          Does the specified resource exist in the repository?
 List<RepositoryResource> getChildren(String parent)
          Return the children of the specified resource.
 void getCurrentFileVersionToWorkspace(String path)
          Deprecated. As of Java API 1.7. Replaced with getLatestFileVersionToWorkspace(String).
 RepositoryFile getFileVersion(String path, String version)
          Get a client representation of the specified resource.
 void getFileVersionToWorkspace(String path, String version)
          Get the specified version of the repository file and bring it into your workspace.
 void getLatestFileVersionToWorkspace(String path)
          Get the latest version of the specified repository file and bring it into your workspace.
 RepositoryResource getResource(String path)
          Get a client representation of the specified repository resource.
 SynchronizationInfo getSynchronizationInfo(String filePath)
          Retrieve the synchronization information for the specified file path.
 Set<SynchronizationInfo> getSynchronizationInfos(String folderPath, boolean includeSubFolders)
          Retrieves the synchronization information for files within a folder.
 List<String> getVersionLabels(String path)
          Get the list of labels for each version of the specified repository file stored in the repository.
 List<RepositoryFile> getVersions(String path)
          Get the list of stored versions of the specified repository file.
 RepositoryFile lockFile(String path)
          Lock the repository file
 void markForAddAndCheckinFileFromWorkspace(String path, boolean versionFile, ResourceCheckinSpecification checkinSpecification)
          Marks a file for add and checks it in to the repository from the workspace.
 RepositoryResource move(String sourcePath, String destinationFolderPath)
          Move the file or folder located by the source path to the destination folder.
 RepositoryResource rename(String path, String name)
          Rename the repository resource.
 void undoCheckout(String path)
          Undo the checkout of the specified resource so others can check out and modify that resource.
 RepositoryFile unlockFile(String path)
          Unlock the repository file
 void updateContentInWorkspaceAndCheckin(String path, String localFilePath, ResourceCheckinSpecification ciSpec)
          Save the local file contents specified into the current user's workspace, and then check the workspace file into the repository.
 RepositoryFile updateFileContents(String path, ResourceCheckinSpecification ciSpec, String localFileLocation)
          Replace the contents of a RepositoryFile with the provided content and make the new version number be as specified.
 RepositoryResource updateResource(RepositoryResource repositoryResource)
          Update the attributes on a repository resource.
 

Method Detail

checkinFileFromWorkspace

void checkinFileFromWorkspace(String path,
                              ResourceCheckinSpecification checkinSpecification)
                              throws RepositoryResourceCheckinException,
                                     RepositoryResourceNotFoundException
Check in the contents of this resource from the current user's workspace to the repository.

Parameters:
path - The file to be checked into the repository.
checkinSpecification - The specification of how the new version should be labeled.
Throws:
RepositoryResourceCheckinException - Thrown when the specified resource was not checked out.
RepositoryResourceNotFoundException - Thrown if the specified resource does not exist in the repository.

If NULL is specified for checkinSpecification, that will be interpreted as a blank comment (and MINOR version update value if the file is versioned).


markForAddAndCheckinFileFromWorkspace

void markForAddAndCheckinFileFromWorkspace(String path,
                                           boolean versionFile,
                                           ResourceCheckinSpecification checkinSpecification)
                                           throws RepositoryResourceCheckinException,
                                                  ResourceNotFoundException
Marks a file for add and checks it in to the repository from the workspace.

Parameters:
path - Path of file to be marked for add and checked in to the repository. Only file paths are supported.
checkinSpecification - The specification of how the new file should be checked in.
versionFile - Whether to version the file in the repository. If false, the version information on the checkinSpecification will be ignored, however, the comment will be added, if provided.
Throws:
RepositoryResourceCheckinException - Thrown when the specified resource was could not be checked in.
ResourceNotFoundException - Thrown when the specified path cannot be found.

checkoutFileToWorkspace

void checkoutFileToWorkspace(String path)
                             throws RepositoryResourceCheckoutException,
                                    RepositoryResourceNotFoundException
Checkout the specified resource from the repository and into the current user's workspace.

Parameters:
path - The repository file to be checked out.
Throws:
RepositoryResourceNotFoundException - The specified resource could not be found in the repository.
RepositoryResourceCheckoutException - The resource was already checked out or locked from change.

checkoutFileToWorkspaceAndDownload

void checkoutFileToWorkspaceAndDownload(String path,
                                        String localFilePath)
                                        throws RepositoryResourceNotFoundException,
                                               RepositoryResourceCheckoutException,
                                               WorkspaceResourceNotFoundException,
                                               IOException
Checkout the specified resource from the repository to the current user's workspace, and then download the content of the workspace file to the specified local file path.

Parameters:
path - The repository file to be checked out.
localFilePath - The path of the local file to write the content of the resource.
Throws:
RepositoryResourceNotFoundException - The resource was not found at the specified location.
RepositoryResourceCheckoutException - The resource could not be checked out (is it already checked out by another user?)
WorkspaceResourceNotFoundException - Resource was checked out but was not found in workspace for download as expected.
IOException

copy

RepositoryResource copy(String sourcePath,
                        String destinationPath)
                        throws RepositoryResourceNotFoundException,
                               RepositoryResourceExistsException,
                               RepositoryResourceCopyException
Copy the file or folder from the source path to the destination path. The destination path is the full path of the newly created copy, so this includes the name of the new object.

Parameters:
sourcePath - The path of the file or folder to copy.
destinationPath - The path of the destination file or folder to create, this includes the name of the newly created copy.
Returns:
The newly created repository resource.
Throws:
RepositoryResourceNotFoundException - The specified source resource was not found.
RepositoryResourceExistsException - A resource already exists at the destination.
RepositoryResourceCopyException - The copy request is not possible, typically the destination path was a child of the source path.

move

RepositoryResource move(String sourcePath,
                        String destinationFolderPath)
                        throws RepositoryResourceNotFoundException,
                               RepositoryResourceExistsException,
                               RepositoryResourceMoveException
Move the file or folder located by the source path to the destination folder.

Parameters:
sourcePath - The path of the file or folder to move.
destinationFolderPath - The folder to move the resource to.
Returns:
The newly moved repository resource.
Throws:
RepositoryResourceNotFoundException - The specified source resource was not found.
RepositoryResourceExistsException - A resource already exists at the new location.
RepositoryResourceCopyException - The move request was not possible.
RepositoryResourceMoveException

createFolder

RepositoryFolder createFolder(String path,
                              boolean createParentFolder)
                              throws RepositoryResourceNotFoundException,
                                     RepositoryResourceExistsException
Create a container at the given location in the repository.

Parameters:
path - The path of the container to create.
createParentFolder - Flag indicating if missing parent containers should be automatically created during this operation.
Returns:
The newly created container.
Throws:
RepositoryResourceNotFoundException - Thrown if createParentContainers is set to false and an expected parent container does NOT exist.
RepositoryResourceExistsException - Thrown if the requested container already exists in the repository.

createFile

RepositoryFile createFile(String path,
                          String localFilePath,
                          String comment,
                          boolean createParentFolders)
                          throws RepositoryResourceNotFoundException,
                                 RepositoryResourceExistsException,
                                 IOException
Create an unversioned file in the repository.

Parameters:
path - The location and name of the ServerResource to be created.
localFilePath - The local file with the contents for the new repository file.
comment - Comment about this newly-created unversioned file.
createParentFolders - Flag indicating if missing parent containers should be automatically created during this operation.
Returns:
RepositoryFile The newly created repository file.
Throws:
RepositoryResourceNotFoundException - Thrown if you did not specify createParentFolders=true, and one of the parent containers specified for this new resource does not already exist.
RepositoryResourceExistsException - Thrown if a file already exists at the specified path.
IOException

createVersionedFile

RepositoryFile createVersionedFile(String path,
                                   String localFilePath,
                                   String comment,
                                   String startingVersion,
                                   boolean createParentFolders)
                                   throws RepositoryResourceNotFoundException,
                                          RepositoryResourceExistsException,
                                          IOException
Create a versioned file in the repository.

Parameters:
path - The location and name of the ServerResource to be created.
localFilePath - The local file with the contents for the new WorkspaceFile.
comment - Comment about this newly created unversioned file.
startingVersion - The initial version label for this file.
createParentFolders - Flag indicating if missing parent containers should be automatically created during this operation.
Returns:
RepositoryFile
Throws:
RepositoryResourceNotFoundException - Thrown if you did not specify createParentFolders=true, and one of the parent containers specified for this new resource does not already exist.
RepositoryResourceExistsException - Throw if a file already exists at the specified path.
IOException

disableVersioningOnFile

RepositoryFile disableVersioningOnFile(String path,
                                       String comment)
                                       throws RepositoryResourceNotFoundException,
                                              RepositoryResourceVersioningException
Disable versioning support for the specified RepositoryFile.

Parameters:
path - The resource to be modified
comment - Comment about this change.
Returns:
The updated resource.
Throws:
RepositoryResourceNotFoundException - The resource was not found at the specified location.
RepositoryResourceVersioningException - Versioning could not be disabled for this resource (is the resource actually versioned?)
IllegalArgumentException - If path provided is to a container.

downloadFile

void downloadFile(String path,
                  String version,
                  String outputFilePath)
                  throws RepositoryResourceNotFoundException,
                         IOException
Download the current contents of a specified ServerResource to the specified local file.

Parameters:
path - The repository file you wish to download.
version - The version of the file you wish, blank if you want the latest version.
outputFilePath - The location you would like the resource contents to be placed.
Throws:
RepositoryResourceNotFoundException - The specified resource was not found at that location.
IOException - Note this has no effect upon your workspace contents.

delete

void delete(String path)
            throws RepositoryResourceNotFoundException,
                   RepositoryResourceDeleteException
Logically delete the specified resource (i.e. it is in your recycle can)

Parameters:
path - The resource to be deleted from the repository.
Throws:
RepositoryResourceNotFoundException - RepositoryResource was not found.
RepositoryResourceDeleteException - RepositoryResource could TCommonnot be deleted.

enableVersioningOnFile

RepositoryFile enableVersioningOnFile(String path,
                                      String comment,
                                      String startingVersion)
                                      throws RepositoryResourceNotFoundException,
                                             RepositoryResourceVersioningException
Turn on versioning support for the specified RepositoryFile.

Parameters:
path - The repository file to be modified
comment - Comment about this change.
startingVersion - The version label to use for the initial version of this repository file.
Returns:
The updated RepositoryFile.
Throws:
RepositoryResourceNotFoundException - The resource was not found at the specified location.
RepositoryResourceVersioningException - Versioning could not be enabled for this resource (is the resource already versioned?)

exists

boolean exists(String path)
Does the specified resource exist in the repository?

Parameters:
path - The path of the repository resource.
Returns:
boolean value indicating if the named resource exists in the repository.

getChildren

List<RepositoryResource> getChildren(String parent)
                                     throws RepositoryResourceNotFoundException
Return the children of the specified resource.

Parameters:
parent - The parent repositoryContainer.
Returns:
List of the children of the parent container.
Throws:
RepositoryResourceNotFoundException - Thrown if the parent resource is not found in the repository.

getResource

RepositoryResource getResource(String path)
                               throws RepositoryResourceNotFoundException
Get a client representation of the specified repository resource.

Parameters:
path - The path of the desired resource.
Returns:
the RepositoryResource located at the given path.
Throws:
RepositoryResourceNotFoundException - Thrown when a repository resource was not found at the given path.

getFileVersion

RepositoryFile getFileVersion(String path,
                              String version)
                              throws RepositoryResourceNotFoundException
Get a client representation of the specified resource.

Parameters:
path - The path of the desired resource.
version - The desired version of that resource.
Returns:
the RepositoryFile located at the given path with the provided version label.
Throws:
RepositoryResourceNotFoundException - Thrown if a resource is not found at that location, or if the specified version label does not exist for that resource.

getVersionLabels

List<String> getVersionLabels(String path)
                              throws RepositoryResourceNotFoundException,
                                     RepositoryResourceVersioningException
Get the list of labels for each version of the specified repository file stored in the repository.

Parameters:
path - The repository file.
Returns:
A list of strings, one for each version of the given resource persisted within the repository.
Throws:
RepositoryResourceNotFoundException - Repository file was not found at the given path.
RepositoryResourceVersioningException - Repository file at the specified path is not versioned.

getVersions

List<RepositoryFile> getVersions(String path)
                                 throws RepositoryResourceNotFoundException,
                                        RepositoryResourceVersioningException
Get the list of stored versions of the specified repository file.

Parameters:
path - The repository file.
Returns:
A list of repository files, one for each version of the given resource persisted within the repository.
Throws:
RepositoryResourceNotFoundException - Repository file was not found at the given path.
RepositoryResourceVersioningException - The repository file is not versioned.

getCurrentFileVersionToWorkspace

@Deprecated
void getCurrentFileVersionToWorkspace(String path)
                                      throws RepositoryResourceNotFoundException,
                                             WorkspaceResourceNotFoundException,
                                             IOException
Deprecated. As of Java API 1.7. Replaced with getLatestFileVersionToWorkspace(String).

Get the current version of the specified repository file and bring it into your workspace.

Parameters:
path - The path of the repository file.
Throws:
RepositoryResourceNotFoundException - Repository file was not found at the given path.
WorkspaceResourceNotFoundException - See exception text.
IOException - See exception text.

getLatestFileVersionToWorkspace

void getLatestFileVersionToWorkspace(String path)
                                     throws RepositoryResourceNotFoundException,
                                            WorkspaceResourceNotFoundException,
                                            IOException
Get the latest version of the specified repository file and bring it into your workspace.

Parameters:
path - The path of the repository file.
Throws:
RepositoryResourceNotFoundException - Repository file was not found at the given path.
WorkspaceResourceNotFoundException - See exception text.
IOException - See exception text.

getFileVersionToWorkspace

void getFileVersionToWorkspace(String path,
                               String version)
                               throws RepositoryResourceNotFoundException,
                                      WorkspaceResourceNotFoundException,
                                      IOException
Get the specified version of the repository file and bring it into your workspace.

Parameters:
path - The path of the repository file.
version - The label of the specific version that should be brought into your workspace.
Throws:
RepositoryResourceNotFoundException - Repository file was not found at the given path.
WorkspaceResourceNotFoundException - See exception text.
IOException - See exception text.

updateFileContents

RepositoryFile updateFileContents(String path,
                                  ResourceCheckinSpecification ciSpec,
                                  String localFileLocation)
                                  throws RepositoryResourceNotFoundException,
                                         IOException,
                                         RepositoryResourceVersioningException,
                                         RepositoryResourceCheckoutException
Replace the contents of a RepositoryFile with the provided content and make the new version number be as specified.

Parameters:
path - The repository file to be modified.
ciSpec - Specification of how the RepositoryFile version number should be modified (if the file is versioned).
localFileLocation - The local file with the contents of the new version of the RepositoryFile.
Returns:
The modified repository file.
Throws:
RepositoryResourceNotFoundException - The repository file was not found at the specified location.
IOException - See the exception text.
RepositoryResourceVersioningException - The provided version specification was illegal or inappropriate for the specified file.
RepositoryResourceCheckoutException - The repository file specified is currently checked out.

Note: This method allows the direct updating of a repository file without going through the typical checkout/checkin process, and has no effect upon your workspace contents.

If NULL is specified for checkinSpecification, that will be interpreted as a blank comment (and MINOR version update value if the file is versioned).


undoCheckout

void undoCheckout(String path)
                  throws RepositoryResourceUndoCheckoutException
Undo the checkout of the specified resource so others can check out and modify that resource.

Parameters:
path - The repository file being released.
Throws:
RepositoryResourceUndoCheckoutException - Thrown if the repository file was not checked out.

updateContentInWorkspaceAndCheckin

void updateContentInWorkspaceAndCheckin(String path,
                                        String localFilePath,
                                        ResourceCheckinSpecification ciSpec)
                                        throws RepositoryResourceNotFoundException,
                                               RepositoryResourceVersioningException,
                                               RepositoryResourceCheckoutException,
                                               IOException,
                                               RepositoryResourceCheckinException
Save the local file contents specified into the current user's workspace, and then check the workspace file into the repository.

Parameters:
path - The file to be updated in your workspace by local content and then checked into the repository.
localFilePath - The path of the local file from which the new contents of the resource are to be read.
ciSpec - Specification of how the RepositoryFile version number should be modified.
Throws:
RepositoryResourceNotFoundException - The resource was not found at the specified path.
RepositoryResourceVersioningException - The specified new version label would be illegal.
RepositoryResourceCheckoutException - The resource was not checked out.
IOException - See the exception text.
RepositoryResourceCheckinException - See the exception text.

rename

RepositoryResource rename(String path,
                          String name)
                          throws RepositoryResourceNotFoundException,
                                 RepositoryResourceExistsException,
                                 RepositoryResourceRenameException
Rename the repository resource.

Parameters:
path - The path of the repository resource to rename.
name - The new name
Returns:
RepositoryResource Resource with the new name.
Throws:
RepositoryResourceNotFoundException - A resource was not found at the specified location.
RepositoryResourceExistsException - A resource already exists in the targetFolder with the name newName.
RepositoryResourceRenameException - The specified resource could not be renamed.

lockFile

RepositoryFile lockFile(String path)
                        throws RepositoryResourceNotFoundException,
                               RepositoryResourceLockException
Lock the repository file

Parameters:
path - The path of the repository file to lock
Returns:
The locked repository file
Throws:
RepositoryResourceNotFoundException - A resource was not found at the specified location.
RepositoryResourceLockException - The specified resource could not be locked.

unlockFile

RepositoryFile unlockFile(String path)
                          throws RepositoryResourceNotFoundException,
                                 RepositoryResourceUnlockException
Unlock the repository file

Parameters:
path - The path of the repository file to unlock
Returns:
The unlocked repository file
Throws:
RepositoryResourceNotFoundException - A resource was not found at the specified location.
RepositoryResourceUnlockException - The specified resource could not be unlocked.

updateResource

RepositoryResource updateResource(RepositoryResource repositoryResource)
                                  throws RepositoryResourceNotFoundException
Update the attributes on a repository resource. Not all attributes are editable, some are managed internally and surfaced as read-only through the API (for example: created, createdBy, lastModified and lastModifiedBy). If any read-only attributes are changed, they will be ignored during the update process. If any attributes are deleted, or new attributes added that are not defined for the object type, those changes will also be ignored.

The expected flow for this call is to first retrieve the resource by calling getResource(String), make any required updates to the attributes and then call this method to persist the changes.

Parameters:
repositoryResource - The repository resource to update
Returns:
The updated repository resource
Throws:
RepositoryResourceNotFoundException - Thrown when a repository resource was not found at the given path.
Since:
1.7
See Also:
RepositoryResource.getAttributes()

getSynchronizationInfo

SynchronizationInfo getSynchronizationInfo(String filePath)
Retrieve the synchronization information for the specified file path.

Provides information about the synchronization state between the file that resides in the workspace and the file that resides in the repository. Files can live independently in the workspace and repository, this method provides information which explains the state of the file. Does it exist only in the workspace or the repository? Does it exist in both places? Was the file synchronized with the repository file at some point? If so, which version of the repository file? Is the file still in sync with the repository file or has the repository file changed? Or has the workspace file changed?

The information provided on the SynchronizationInfo object allows users to determine if they are out-of-sync with the repository file and decide if they should pull changes from the repository into the workspace or push changes from the workspace into the repository; or decide to do nothing at all and continue working with the file contents they have.

If the path provided does not exist a SynchronizationInfo will still be returned, SynchronizationInfo.FileStatus.NON_EXISTENT will be set and all other file info attributes will be null. If the path is to a folder an IllegalArgumentException will be thrown.

Parameters:
filePath - The file path to retrieve synchronization information for.
Returns:
The synchronization information for the file.
Since:
1.7

getSynchronizationInfos

Set<SynchronizationInfo> getSynchronizationInfos(String folderPath,
                                                 boolean includeSubFolders)
                                                 throws RepositoryResourceNotFoundException
Retrieves the synchronization information for files within a folder. This method can retrieve the synchronization information for the files immediately within the folder, or it can recurse the entire subfolder structure and retrieve information on all the files within the folder subtree.

If there are no child files then an empty Set will be returned. If the path is to a file an IllegalArgumentException will be thrown.

Parameters:
folderPath - The path of the folder to use.
includeSubFolders - If false retrieve the synchronization information for files within the folder specified (immediate children), if true retrieve the synchronization information for files within the entire subtree (recurses into all subfolders if they exist).
Returns:
The synchronization information for the files found within the folder. If there are no child files found then an empty Set will be returned.
Throws:
RepositoryResourceNotFoundException - Thrown when a repository resource was not found at the given folder path.
Since:
1.7


Copyright (c) 2014, SAS Institute Inc., Cary, NC, USA