| Oracle Repository API and Model Reference Guide |
|
Oracle Repository's version control and configuration management facilities can be used to manage operating system files and folders in much the same way as other repository objects. The repository File Service provides a bridge between the operating system file system and the contents of folders and files in the repository. To do this, the contents of operating system file objects are replicated in appropriate repository objects (elements of type PRIMARY_ACCESS_FILE), and then the two copies can be kept in step with each other.
Notes:
The File Service API for Java provides methods to enable Java applications to support Window client side operations for managing operating system files as repository objects:
Notes:
It is assumed that normally, any editing of the file's contents is done using file system facilities (editors, graphics tools, for example), and that the repository is used for managing versions of the contents (creating versions, comparing and merging, for example).
Synchronization is a scheme for keeping the contents of operating system files in step with their equivalents in the repository, and vice versa, so that when one set of contents changes, the other set of contents are refreshed to reflect the changes. Synchronization can therefore either cause the file system be refreshed from the repository (download), or cause the repository contents to be refreshed from the file system (upload).
One of two approaches to synchronization can be adopted by the caller:
Notes:
Synchronization can operate at file level, container level, or workarea level.
If a file has changed in both the repository and the file system, then the synchronization process attempts to rename the file system file to <filename>.KEEP and then downloads the repository copy. The repository user must then decide which copy is required.
The synchronization process maintains and compares the CRC values found in:
and either uploads or downloads depending on the results, as follows:
If the repository and .RVI CRCs are the same, this is taken to mean the file system file has changed. If the file system CRC and the .RVI CRC are the same, this is taken to mean that the repository file has changed. If all three CRCs are different, both the file system file and the repository file have changed. In that case, the synchronization process:
Following the first successful synchronize operation, further attempts at synchronization require the .RVI file to be available.
Note: Using upload or download does not create or use a .RVI file.
To perform file synchronization, the caller instantiates the FileService class, and calls its synchronize method.
During a synchronize operation, files that have been 'removed' from the repository by deletion or by exclusion from the workarea can also optionally be deleted from the file system.
For this to occur, the file must have been synchronized at least once prior to being removed from the repository, otherwise it is considered to be a new file (and uploaded accordingly).
If you choose not to delete a 'removed' file from the file system, it continues to be marked as a removed file (unless the repository file reappears as a result of refreshing the workarea). To get the file to be uploaded to the repository again, it must be explicitly uploaded. To process a number of removed files in this way, upload a parent folder with the FS_RECURSE flag set and the FS_OVERWRITE flag unset (that is, upload new files only).
Deletion of 'removed' folders is not currently implemented.
A folder mapping is an association between a root container object in the repository and a folder (directory) managed by the operating system on a client computer that has access to the repository. The presence of mappings enables the synchronization of operating system files with the contents of PRIMARY_ACCESS_FILE objects in the repository.
Notes:
A repository container can be mapped to any valid operating system path that does not subsume another mapping, or is that is not subsumed by another mapping. For example, if there is an existing mapping fol1 to d:\repos1\myfol , the following mappings would be disallowed:
d:\repos2 and d:\repos1\x would be valid for further mappings.
To perform mapping, the caller uses the ReposFolderMapping class, and calls the appropriate mapping method. Folder mapping can also be performed using the Repository Object Navigator.
To perform file upload and download, the caller instantiates the FileService class, and calls the appropriate upload or download method.
Upload and download of individual files do not require a mapping: a file to be uploaded or downloaded is specified by its repository path or its IRID.
To upload or download files, the caller must have at least the SEL access right on the container of the file object.
Note: For any operation that results in a new file or folder being inserted in the repository (that is, during synchronization or upload), the File Service turns off uniqueness checking for the duration of that operation.
The container of any file to be downloaded must be checked out.
Individual files, specified by repository path, can be downloaded from the repository. The version downloaded is the version currently visible in the current workarea.
The repository file object is not affected in any way by the download process.
If it is registered as 'compressed', it is decompressed when downloaded.
If a file to be downloaded is not in the operating system file system, the API creates a new file.
On download, the API updates the file's time stamp and file permissions according to the values in the repository. A file that is checked in in the repository is marked as read-only in the file system when it is downloaded.
The caller must specify whether to overwrite the contents of a file that already exists in the specified path in file system.
The content of files in the repository is not altered in any way during upload or download. However, when a file is downloaded to a client, the contents must be altered to conform to the EOL conventions used by the operating system of the client.
UNIX uses one EOL marker and Windows operating systems (including DOS) use different EOL marker (LF in UNIX, CR/LF in Windows). The File Service converts EOL characters from one to the other as specified in a flag (FS_WIN_TXT_FORMAT or FS_UNX_TXT_FORMAT) passed as a parameter to the download and synchronize API methods. Another flag (FS_NO_TXT_FORMAT) can be used to specify that no conversion is to be performed.
When processing a synchronize operation, if the flag is not specified, the File Service uses any setting specified in the mapping; otherwise the operation fails.
When doing the conversion, the File Service does not alter any occurrence of the target EOL characters that are already present in the file.
Do not specify conversion for:
For very large files, there may be a performance penalty if conversion is peformed.
When processing a synchronize operation, the algorithm that calculates a file's CRC treats two files with the same content but different EOL markers as identical.
Individual files can be uploaded to the repositorym (either explicitly or as part of synchronization). If a file to be uploaded is not in the repository, the API creates a new PRIMARY_ACCESS_FILE object if the target container is currently checked out. If the file is currently checked in it is skipped and an error is logged for that file.
Notes:
Filenames in Windows file systems, including DOS, are treated by the operating system as case-insensitive, so that 'Myfile.txt', 'MYFILE.TXT', and 'MyFile.txt' are all equivalent as filenames. Windows graphical user interface tools such as the Explorer may display filenames in some particular display format, but the underlying operating system treats 'Myfile.txt', 'MYFILE.TXT', and 'MyFile.txt' as one filename.
When a file is uploaded to the repository (or when a required folder is created) the actual name of the file or folder as known to the client's operating system (not its displayed name) is stored in the Name property of the corresponding object in the repository. When the file is downloaded, the name stored in the Name property of the object in the repository is re-used exactly to name the object in the operating system. That is, the repository does not transform filenames in any way during download or upload.
However, the repository does its own uniqueness checking of filenames; case insensitivity for filenames is one asspect of this checking, and can affect whether a new filename is rejected or accepted. The case sensitivity policy setting in the repository governs this aspect of uniquenes for filenames in the repository. An administrator can use either the setpolicy command in the Command Line Tool or Version > Set Policy in the Repository Object Navigator to say how the repository should check filenames for uniqueness, with effects as shown in the following table:
| If case sensitivity policy setting is... | and if file 1 exists, with name... | and file 2 is to be added, with name... | the result is... |
| ON (default) | myfile.txt | MyFile.txt | MyFile.txt accepted. |
| OFF | myfile.txt | MyFile.txt | MyFile.txt rejected. |
| ON or OFF | myfile.txt | myfile.txt | myfile.txt already exists. |
Note that if you set the policy OFF, this may incur some performance overhead, because the repository's indexes can no longer be used as the sole constraint. For this reason, the policy is ON by default.
Before switching this policy off, produce a report and use it to check for any names that would become duplicate names, and resolve any duplicates manually by renaming files. See also the description the handling of case sensitivity in the Naming Service.
Every time a file is uploaded, its CRC value is calculated by the API. If the file is successfully stored in the repository (either as part of a synchronize operation or or on explicit upload), the calculated CRC is stored with it.
As part of synchronization, if both repository and file system files exist, the file's CRC is calculated before uploading (for comparison with the CRC stored in the repository). In this case, the CRC is not recalculated on upload, but it is stored after the upload (if it occurs).
Upload operations (including uploads that happen as part of synchronization) cause CDAPI activities to be opened and closed (to commit operations) on the server.
The value set for commit frequency determines how often the FileService opens and closes activities as it uploads. A commit frequency of n means that activities will be opened and closed for every n files uploaded. Thus, if 65 files are to be uploaded, and commit frequency is set to 20, the File Service will open and close four activities (one for the last 5 files). A commit frequency of 0 means no activities are opened or closed. This enables the caller to control whether and when the FileService commits.
The commit frequency can be set in two ways:
Warning: If no persistent stored commit frequency is set, and a FileService object does not set its own value, the default is 0. In that case, the caller must either open and close activities explicitly, or issue commit statements in respect of specific operations performed through the FileService object, otherwise those operations will not be committed to the repository.
File compression and decompression take place transparently at appropriate points in upload or download operations (either when these operations are explicitly requested, or as part of synchronization).
For compression to be performed, the name of a file being uploaded or downloaded must conform to a pattern registered in the File Type Registry. You do this by assigning the pattern the COMPRESSED attribute in the File Type Registry in the Repository Object Navigator.
For a given filename myfile, note the following:
For further details of the setting and options available in the File Type Registry, see the online help for the Repository Object Navigator.
When a compressed file is being downloaded, it is decompressed during the download operation) when it is being uploaded, it is compressed and the result stored in the COMPRESSED_CONTENTS column of the PRIMARY_ACCESS_FILE object in the repository.
In the context of the File Service API for Java, the repository path for a FILE or container is the list of containers in the context workarea, each separated by the java.IO.File.separatorChar in the hierarchy containing the target file or folder, and its name. For example:
Several methods in the File Service API throw FileServiceException during synchronization and upload and download operations. FileServiceException is derived from IOException: it might be thrown from ReposFileInputStream. Each FileServiceException also has a CWException constructed by the FileService, holding details of IOException or a SQLException or any other error encountered by the File Service API.
FileServiceException is an Exception) the message text is always relates to the system level exception (for example, IOException). To obtain the repository 'version' of the error event, the CWException can be extracted from the FileServiceException using FileServiceException.getCWException.
A SQLException is converted to a CWException within FileServiceException. An IOException gives rise to a FileServiceException.
FileServiceException might also also hold details of any other system exception that caused an error. To get details of any such exceptions, RTTI can be used to examine the object returned by a call to FileServiceException..
For details of the various access rights and system privileges, see The Privileges and Access Rights API.
The File Service API for Java is implemented in the package oracle.repos.services.file.
The File Service API for Java requires an active RepositoryConnection object. The RepositoryConnection class contains a method for (among other things) connecting to a repository and setting the context workarea. Before any File Service API methods can be called, a context workarea must be set. All methods described here target the currently visible version of a file or container in the context workarea.
The following methods on RepositoryConnection must be called before using any of the API calls described here:
public RepositoryConnection (String strUser, String strPass, String strNet8)
Where:
strUser is the repository user name.
strPass is the password.
strNet8 is the Net8 service alias.
This creates a new RepositoryConnection object, establishing a new JDBC connection to a database with the specified user name, password and Net8 service alias.
public RepositoryConnection (Connection connection)
Where:
connection is the existing JDBC connection.
Creates a new RepositoryConnection object based on an existing JDBC connection.
When a repository is installed, it is given a universally unique ID (UUID). Some File Service API methods require the unique ID of the repository as a parameter. Callers can obtain the UUID of a repository in the following ways:
public String getUID ()
declare uuid varchar2(128); begin select inf.value into uuid from rm$info inf where inf.name ('UUID') end)
The following methods on RepositoryConnection can be used to set the context workarea for operations using the File API:
public void setActiveWorkArea (String strName, RID id) public void setActiveWorkArea (String strName)
The following method on RepositoryConnection closes the repository connection. The underlying JDBC connection is terminated without implicitly committing data, all JDBC resources and any default datasets are released.
public void close ()
Note: RID and GID are wrapper classes for holding large integers such as IRIDs, IVIDs, and workarea IDs. A RID or GID returned by a method in the API can be passed as a parameter to other methods, without modification.
Note: Native methods of the File Service API require the jrnfs dynamic link libraries to be available. Therefore the File Service API does not run on Unix.
Class FileService public native static void setTimestamp (String fileName, long timeStamp);
Where:
fileName is the full file system file name
timeStamp is the time stamp value in the format provided by java.sql.Timestamp.toString ()
Sets a file system file time stamp. The time stamp must be in the form provided by java.sql.Timestamp.toString ().
Note: To do this, create a java.sql.Timestamp and pass in the result of the toString () method to this function.
Class FileService public native static BOOLEAN setReadOnly (String fileName);
Where:
fileName is the full file system file name.
Sets the specified file or directory to read-only .
Class FileService public native static BOOLEAN setReadWrite (String fileName);
Where:
fileName is the full file system file name.
Sets the specified file or directory to read-write .
Class FileService public FileService (RepositoryConnection conn);
Where:
conn is a suitably initialized RepositoryConnection object.
Constructor for entry point to repository file services.
The context workarea is assumed to be correctly set using the SetActiveWorkarea method on RepositoryConnection.
Class FileService public FileService (RepositoryConnection conn, PrintWriter out);
Where:
conn is the RepositoryConnection to repository. Workarea is assumed to be correctly set (if required)
out is a PrintWriter to direct output stream.
Constructor for entry point to repository file services.
Class FileService public Vector uploadByName (String strOSPath , String strNameFilter , String strReposPath , String strNameTarget , RID ctxtFolderID , int flags)
Where:
strOSPath is the operating system path for the immediate parent folder of files to be uploaded.
strNameFilter is the filter specifying which files in strOSPath to upload.
strReposPath is a repository path specifying the destination of the uploaded files.
strNameTarget is not used) set to NULL.
ctxtFolderID is (optionally) the IRID of the target container.
flags specifies a set of processing flags.
Copies named files from strOSPath to strReposPath.
Names are specified by a filter pattern, strNameFilter. Valid wild cards are "*" , which matches any string pattern, and "?", which matches any single character.
This method does not perform data integrity checks before uploading. The appropriate column of the repository file object is replaced by the content of the file system file. If the repository file does not exist, it is created.
If the repository file object is currently checked in, it remains unchanged.
The repository context container ctxtFolderID is optional (set to NULL if not used) and specifies the IRID of the target container (the last container in the repository path strReposPath).
If flags specifies FS_RECURSE, the copy operation is repeated for files in any file system sub folders.
If new files are added to a container, and if flags specifies FS_VERSION_PARENT, the container is versioned. That is, if the container is checked in:
Returns a vector of FileServiceNfo elements, each containing information about a file or folder that has been processed.
A FileServiceNfo object has the following data members:
public RID rid public String strName public String strOSPath public String strReposPath public String strStatus public String strKind public Date OSTimestamp public long oldLobLen public long fileSize public long crc public BOOLEAN bResult public BOOLEAN bIsFile //internal File Service values... should always be null when object returned to client OracleBlob blob OracleClob clob OracleBlob zlob
The bResult value for each element indicates whether the operation was successful (TRUE) or not (FALSE)
Class FileService public Vector downloadByName (String strOSPath , String strNameFilter , String strReposPath , String strNameTarget , RID ctxtFolderID , int flags)
Where:
strOSPath is the operating system path for the immediate parent folder of files to be downloaded.
strNameFilter is the filter specifying which files in strReposPath to download.
strReposPath is a repository path specifying the source of the downloaded files.
strNameTarget is not used) set to NULL.
ctxtFolderID is (optionally) the IRID of the source container.
flags specifies a set of processing flags.
Copies named files from strReposPath to strOSPath
Names are specified by a filter pattern, strNameFilter. Valid wild cards are "*" , which matches any string pattern, and "?", which matches any single character.
Does not perform data integrity checks before downloading. The content of the file system file is replaced by the appropriate column of the repository file. If the file system file does not exist, it is created.
The repository context container ctxtFolderID is optional (set to NULL if not used) and specifies the IRID of the source container (the last folder in strReposPath).
If flags specifies FS_RECURSE, files in any file system sub folders are recursed into and the copy operation repeated.
Returns a vector of FileServiceNfo elements, each containing information about a file or folder that has been processed.
Class FileService public BOOLEAN uploadToRID (InputStream uploadStream , RID rid , long osTimestamp) throws SQLException, IOException)
Where:
uploadStream is the java.io.InputStream which will provide the upload data.
rid is the repository file ID to upload to.
osTimestamp is an optional client specified time stamp. The time stamp is expected to be in standard java format - the number of milliseconds since Midnight, Jan 1st 1970 (that is, UTC milliseconds) - that is, a valid value can be obtained from java.io.File.lastModified ();
Uploads an InputStream to the specified repository file. The repository file must exist and be checked out) otherwise the upload operation fails. The function uses the File Type Registry to determine whether the file is binary or text.
Note: The repository stores time stamps as UTC seconds, not milliseconds. However, clients should not alter the time stamp to account for this: the upload method performs the conversion automatically. Similarly, download methods re-convert repository stored time stamps to Java format. If the client does not provide a time stamp (osTimestamp (0), then the system time (System.currentTimeMillis (); is used to provide the Timestamp.
Class FileService public BOOLEAN uploadToRID (InputStream uploadStream , RID rid , Date osTimestamp) throws SQLException, IOException;
Where:
uploadStream is the Java stream object from which to read the file to be uploaded.
rid is the IRID of the repository file object to upload to.
osTimestamp is the operating system time stamp of the file.
Class FileService public BOOLEAN uploadToRID (String strOSPath , RID rid , BOOLEAN bLock , int flags) throws SQLException, IOException;
Where:
strOSPath is the full file system path, including file name (for example, "C:\fol1\file.txt")
rid is the repository file ID to upload to.
bLock specifies whether the file system file is locked (file permissions set to read-only) after upload. If bLock is FALSE, the file permissions are left unchanged.
bOverwrite specifies whether the data integrity checks should be made. If TRUE, the file system file overwrites the repository file, regardless of which file is newer. If FALSE, the upload is aborted if the repository file is newer than the file system file. (This parameter is redundant and will be removed in a later version; callers should always specify TRUE, because FALSE prevents upload.)
Uploads a file system file to the specified repository file. The repository file must exist and be checked out or the upload operation fails. The function uses the File Type Registry to determine whether the file is binary or text.
API Methods List
setCommitFreq
Class FileService public void setCommitFreq(int nCommitFreq)
Where:
nCommitFreq specifies the number of uploads after which the current activity is closed and a new activity opened.
Sets the value for the commit frequency for the lifetime of the FileService object. This value overrides any value stored using setStoredCommitFreq.
API Methods List
getCommitFreq
Class FileService public native static int getStoredCommitFreq()
Returns the persistent value (if any) for the commit frequency stored in the Windows NT Registry.
API Methods List
setStoredCommitFreq
Class FileService public native static boolean setStoredCommitFreq(int nCommitFreq);
Where:
nCommitFreq specifies the number of uploads after which the current activity is closed and a new activity opened.
Stores a persistent value for the commit frequency in the Windows NT Registry.
Returns FALSE if the value could not be stored.
API Methods List
getStoredCommitFreq
Class FileService public int getCommitFreq()
Returns the value (if any) for the commit frequency previously stored using setCommitFreq.
API Methods List
setCommitFreq
Class FileService public void close()
Closes the the FileService object and releases any open resources (such as database cursors). It is the responsibility of the caller to close a FileService object explicitly once the object is finished with, since there is no guarantee close will be called automatically until the main thread is closed.
Note:
For performance reasons, the resources created by a FileService object are not released until FileService.close() is called. This means that any FileService user (for non-static methods) must call close() when they have completely finished with a FileService object. Otherwise, there will be unclosed cursors may be left on the server.
This arrangement also means FileService objects can be re-used, which may result in faster repeat operations. For example, repeated calls to upload several specific files, do result in the re-opening of database cursors.
Putting the above two points together: Typically you will want to catch the FileService exception and re-throw / examine the CWException, then close the resources created by the FileService object:
FileService fs=null)
try
{
fs (new FileService(..);
fs.uploadByName(..);
}
catch(FileServiceException fsx)
{
throw fsx.getCWException(); //pass on the CWException
}
finally
{
try
{
if (fs !(null) fs.close();
}
catch(FileServiceException fsx2)
{
throw fsx2.getCWException(); //this shouldn't happen very often, if ever...
}
}
Class FileService public boolean downloadFromRID (String strOSPath , RID rid , int flags);
Where:
strOSPath is the full operating system path, including file name (for example, "C:\fol1\file.txt")
rid is the repository file ID to download from.
flags specifies a set of processing flags.
Downloads a repository file to the specified file system file. If the file does not exist it is created. If flags specifies FS_OVERWRITE, the file system file is overwritten, regardless of whether it is newer than the repository file or not.
The API updates the file's time stamp and file permissions according to the values in the repository. A file that is checked in in the repository is marked as read-only in the file system when it is downloaded.
Throws SQLException, IOException or FileServiceException on error.
Class FileService public void downloadFromRID (String strOSPath , RID rid , boolean block , boolean boverwrite);
Superseded method see downloadFromRID
Class FileService public ReposFileInputStream getDownloadStream (RID rid);
Where:
rid is the repository file ID to be downloaded by the stream.
Returns a ReposFileInputStream that can be used to read the contents of a repository file. The specified file must exist.
Callers should not attempt to read more than n bytes (where n (getMaxChunkSize () bytes) at a time from the returned ReposFileInputStream.
Throws SQLException on error.
Note: Class ReposFileInputStream extends java.io.inputstream.
Class FileService public static int getMaxChunkSize ();
Calculates and returns the maximum chunk of data that can be read/written by the File Service.
Files are read and written in n-sized chunks (where n=getMaxChunkSize () chunks (if the file size is bigger than n).
Class FileService public static long javaTimeToRepos (long javaTimestamp);
Where:
javaTimestamp is the Java time stamp in UTC milliseconds to be converted a repository time stamp (UTC seconds).
Converts a Java time to repository time. Java time is UTC milliseconds (the number of milliseconds since Midnight Jan 1st 1970). Repository time is UTC seconds (the number of seconds since 00:00 1-1-1970.)
Class FileService public static long reposTimeToJava (long reposTimestamp);
Where:
reposTimestamp is the repository time stamp in UTC seconds to be converted a Java timestamp (UTC milliseconds).
Converts a repository time to Java time. Java time is UTC milliseconds (the number of milliseconds since Midnight Jan 1st 1970). Repository time is UTC seconds (the number of seconds since 00:00 1-1-1970).
Class FileService public long getFileCRC (File osFile);
Where:
osFile is the file system file from which to calculate the CRC (must be readable).
Gets a repository compatible CRC for the specified file system file.
Throws an IOException on error
Class FileService public Vector synchronize (String strUUID , GID gidWorkareaID , String strReposPath , String strNameFilter , int flags)
Where:
strUUID is the repository UUID.
gidWorkareaID is the ID of the context workarea, and is required.
strReposPath is an optional repository path.
strNameFilter is a pattern filter specifying file names to be included.
flags specifies a set of processing flags.
Synchronizes repository a workarea, a set of containers, and a set of files. For this form of the synchronize method, the caller must provide the repository UUID, a valid workarea ID, and the name pattern for the files to be synchronized.
strUUID and gidWorkareaID establish the mapping to be used; strReposPath and strNameFilter establish the repository context (the set files and folders) to be synchronized.
If strReposPath is not NULL, it is used together with strNameFilter to establish the context in which to perform the synchronization operation. Otherwise, the whole workarea is used as the context.
If strNameFilter is not NULL, it is used together with strReposPath to establish the context in which to perform the synchronization operation. Otherwise, all files in the workarea or the repository path are used in the synchronization operation.
Given the following (simplified) repository directory structure:
/folder1/folder2/folder3/ /folder1/folder4/
and given a strReposPath of "/folder1/folder2", then:
Returns a vector of FileServiceNfo elements.
Notes:
API Methods List
RepositoryConnection.getUID()
uploadByName()
Class FileService public Vector synchronize (String strOSPath , String strReposPath , String strNameFilter , int flags)
Where:
strOSPath is the file system path identifying the folder to be synchronized.
strReposPath is the corresponding repository path.
strNameFilter is a pattern filter specifying file names to be included.
flags specifies a set of processing flags.
Synchronizes repository workareas, containers, and FILES. This form of the synchronize method does not require a mapping. strOSPath and strReposPath are assumed to exist. If not, results are undetermined.
Returns a vector of FileServiceNfo elements.
Notes:
API Methods List
RepositoryConnection.getUID ()
Class ReposFolderMapping provides methods for setting and managing mappings between a file system folders and repository root containers.
Class ReposFolderMapping public ReposFolderMapping ()
Constructor.
On creation of a ReposFolderMapping object, a native DLL is loaded, ready to fetch relevant system information.
Class ReposFolderMapping
public static FileServiceNfo getMapping (GID gidFolderIRID
, String strReposUUID
, GID gidWorkareaID)
Where:
gidFolderIRID is the IRID of a repository root container.
strReposUUID is the repository UUID.
gidWorkareaID is the ID of the workarea containing the root container.
Gets the repository container information associated with the folder mapping (the container IRID). The folder must be a repository root container. If the folder is mapped, a FileServiceNfo object is returned with the strName, strOSPath and RID parameters set.
Note: Only the IRID of the returned RID is set; the IVID is set to 0 (a mapped container's IVID is not stored).
It returns details of the container if successful (with only the IRID of the RID being valid), NULL otherwise.
API Methods List
RepositoryConnection.getUID ()
Class ReposFolderMapping
public static RID getUploadMapping (GID gidFolderIRID
, String strReposUUID
, GID gidWorkareaID)
Where:
gidFolderIRID is the IRID of a repository root container
strReposUUID is the repository UUID
gidWorkareaID is the workarea ID
Gets the repository container reference associated with the folder mapping key.
Note: Only the IRID of the returned RID is set; the IVID will be set to "0", as a mapped container's IVID is not stored.
It returns the container IRID (in a RID, with the IVID set to 0) if successful, NULL otherwise.
It returns the container name as a string if successful, NULL otherwise.
API Methods List
RepositoryConnection.getUID ()
Class ReposFolderMapping
public static String getFolderName (GID gidFolderIRID
, String strReposUUID
, GID gidWorkareaID)
Where:
gidFolderIRID is the IRID of a repository root container.
strReposUUID is the repository UUID.
gidWorkareaID is the workarea ID.
Gets the repository container name associated with the folder mapping.
It returns the file system path as a string if successful, NULL otherwise.
API Methods List
RepositoryConnection.getUID ()
Class ReposFolderMapping
public static String getDownloadMapping (GID gidFolderIRID
, String strReposUUID
, GID gidWorkareaID)
Where:
gidFolderIRID is the IRID of a repository root container.
strReposUUID is the repository UUID.
gidWorkareaID is the workarea ID.
Returns the file system folder path associated with the folder mapping key.
It returns the file system path as a string if successful, NULL otherwise.
API Methods List
RepositoryConnection.getUID ()
Class ReposFolderMapping
public static BOOLEAN setMapping (GID gidFolderIRID
, String strPath
, String strReposUUID
, GID gidWorkareaID
, BOOLEAN ForceDefault)
Where:
gidFolderIRID is the IRID of a repository root container.
strPath is the file system path as a string.
strReposUUID is the repository UUID.
gidWorkareaID is the workarea ID.
bForceDefault indicates whether to overwrite registry settings in the Repository Object Navigator.
Creates a mapping between a repository container (gidFolderRef) and file system path (strPath) using a string key-value (strFolderIRID).
It returns TRUE if successful, FALSE otherwise.
API Methods List
RepositoryConnection.getUID ()
Class ReposFolderMapping
public static BOOLEAN setMapping (GID gidFolderIRID
, String strPath
, String strReposUUID
, GID gidWorkareaID
, String strFolderName
, BOOLEAN bForceDefault)
Where:
gidFolderIRID is the IRID of a repository root container.
strPath is the file system path as a string.
strReposUUID is the repository UUID.
gidWorkareaID is the workarea ID.
strFolderName is the container name.
bForceDefault indicates whether to overwrite registry settings in the Repository Object Navigator.
Creates a mapping between a repository container (gidFolderRef) and file system path (strPath) using a string key-value (strFolderIRID).
This method also enables the folder name to be stored.
It returns TRUE if successful, FALSE otherwise
API Methods List
RepositoryConnection.getUID ()
Class ReposFolderMapping
public static GID[] getAllFolderMappings (String strReposUUID
, GID gidWorkareaID)
Where:
strReposUUID is the repository UUID
gidWorkareaID is the workarea ID
Gets a list of all the folder mappings available on the client computer. It returns a GID array of mapped container IRIDs if successful, null (or empty array) otherwise
API Methods List
RepositoryConnection.getUID ()
Class ReposFolderMapping
public static BOOLEAN removeMappingKey (GID gidFolderIRID
, String strReposUUID
, GID gidWorkareaID)
Where:
gidFolderIRID is the IRID of a repository root container
strReposUUID is the Repository UUID
gidWorkareaID is the workarea ID
This method removes the mapping key for a specific container in a specific workarea of a specific repository. It returns TRUE if successful, FALSE otherwise
RepositoryConnection.getUID ()
API Methods List
Class ReposFolderMapping
public static BOOLEAN removeAllMappingKeys (String strReposUUID
, GID gidWorkareaID)
Where:
strReposUUID is the repository UUID.
gidWorkareaID is the workarea ID.
This method removes all mapping keys for a specified repository workarea. It returns TRUE if successful, FALSE otherwise
RepositoryConnection.getUID ()
API Methods List
A FileServiceException holds generic exceptions encountered by the FileService and any corresponding CWException (Repository specific error).
The underlying system exception (whatever caused the error - for example, SQLException, IOException) is used to populate the error message text and a corresponding CWException is added, indicating the repository process that failed.
If the exception is an IOException, then the class is a valid IOException, with the addition of a CWException providing FileService error details.
If the exception is a SQLError, then a ReposServiceException is held (as a CWException, which is its base class), and clients can cast the CWException to ReposServiceException to get details of the SQL error.
Any other error is held as an Exception (typically arising from an IO error, a SQL error, or a data format error) which the caller can inspect using RTTI.
Class FileServiceException provides the following methods:
Class FileServiceException public CWException getCWException()
Returns the CWException associated with this FileServiceException.
Note: The CWException could be a ReposServiceException if the error was a server error. Therefore, to recover SQL error details, test whether the returned exception is a ReposServiceException, and if so, cast the CWException to ReposServiceException.
Class FileServiceException public Exception getException()
Returns the generic Java Exception that caused this FileServiceException to be generated. Returns NULL if any of the following is true:
Processing flags are as follows:
| FS_RECURSE ( 0x0000001) |
Process files in sub-containers sub directories. |
| FS_VERSION_PARENT (0x0000002) |
Version the target container when a file is uploaded. |
| FS_ADD_NEW_FILES (0x0000004) |
On upload operations, for each new file uploaded, create it in the repository. |
| FS_OVERWRITE (0x0000008) |
Overwrite the file, regardless of whether it is newer than the repository file or not. |
| FS_WIN_TXT_FORMAT (0x0000010) |
For any download operation, ensure the file has Windows end-of-line markers. |
| FS_UNX_TXT_FORMAT (0x0000020) |
For any download operation, ensure the file has UNIX end-of-line markers. |
| FS_SYNC_DEL_OS (0x0000040) |
When synchronizing, if a file has been deleted in the repository, delete its corresponding file in the file system. |
| FS_OS_LOCK (0x0000080) |
Lock the file after downloading it (for the downloadFromRID method only). |
| FS_OS_MKDIRS (0x0000100) |
When processing downloadFromRID, attempt to create all required directories. If this is not specified and a required directory is not found, the call fails. |
| FS_NO_TXT_FORMAT (0x0000200) |
For synchronization only, ignore any default text format specified via the mapping. |
Notes:
int flags (0)
flags =FS_FLAG_1 | FA_FLAG_2;
Class FileService public static native long ReposCRC(long crc, byte[] b, int len);
Where:
crc is the previous CRC value to be updated. The first call to this method should set CRC = 0
b is a data buffer holding an array of bytes
len is the amount of the data buffer to be passed into the CRC calculating function.
Updates the repository CRC as the standard CRC code with all carriage-return ('\r') characters removed from the data buffer. Use this method to calculate a CRC code for a data stream, that is valid in the repository.
Returns The updated crc, or 0 on error.
Class FileService
public static int OSFileOpen (Object obRef
, String strFileName) throws FileServiceException
Where:
obRef is a pointer to calling class
strFileName is the fully qualified filename (for example "d:\temp\myfile.txt")
Opens the specified operating system file and returns the stream pointer (FILE*) as an int. Clients should use this pointer in calls to OSFileWrite and OSFileClose. Once you have opened a file stream you must close it again.
Returns the stream pointer.
Class FileService public static void OSFileClose(Object obRef, int hFile) throws FileServiceException
Where:
obRef Pointer to calling class
hFile Stream pointer/handle(FILE*). This should be an int value returned from OSFileOpen
Closes the operating system file associated with the file handle (stream pointer) passed in. The file handle can be obtained from OSFileOpen Throws FileServiceException on error
Class FileService
public static int OSFileWrite (Object obRef, int hFile, byte[] b
, int offset, int len,int txtFmt, int nLastChar)
throws FileServiceException
Where:
obRef is a pointer to calling class
hFile is a File stream pointer obtained from OSFileOpen
b is the byte data to be written to the file
offset is the position into the data to be written from (that is, data is to be read from the specified offset onwards).
txtFmt indicates text conversion requirements, and is one of:
<txtFmt = 0> No conversion: File is written "as is" to disk
<txtFmt = 1> DOS --> UNIX. Excludes carriage-return characters from being written to the file
<txtFmt = 2> UNIX --> DOS Converts any single line-feed characters into line-feed / carriage-return pairs. Note: Existing CR-LF pairs are ignored.
nLastChar indicates whether the last character of the previous data chunk to be written was a CR or not. This is neccessary when performing a UNIX to DOS conversion and an existing CR-LF pair spans two data chunks.
Writes data to the specified operating system file, performing text conversion if required.
Returns Return code (rc) indicates whether the write was successful and also whether the last byte of the data chunk was a CR, and is one of:
rc == 1: write succeeded, last byte was not a CR
rc == 2: write succeeded. last byte was a CR