org.apache.subversion.javahl
Class SVNUtil

java.lang.Object
  org.apache.subversion.javahl.SVNUtil

public class SVNUtil
extends Object

Nested Class Summary

static class	SVNUtil.ConflictDisplayStyle Style for displaying conflicts in merge output.
static class	SVNUtil.Credential Generic credential description.
static class	SVNUtil.CredentialTypeMismatch Exception used by calling the wrong accessor on Credential for the given credential type.
static class	SVNUtil.DiffOptions Options to control the behaviour of the file diff routines.

Field Summary

static byte[]	EOL_CR Use the carraige-return code point ('\x0d') for the newline separator.
static byte[]	EOL_CRLF Use carriage-return/linefeed sequence ('\x0d\x0a') for the newline separator.
static byte[]	EOL_LF Use the linefeed code point ('\x0a') for the newline separator.

Constructor Summary

SVNUtil()

Method Summary

static Map<String,byte[]>	buildKeywords(byte[] keywordsValue, long revision, String url, String reposRootUrl, Date date, String author) Build a dictionary of expanded keyword values, given the contents of a file's svn:keywords property, its revision, URL, the date it was committed on, the author of the commit and teh URL of the repository root.
static byte[]	canonicalizeNodeProperty(String name, byte[] value, String path, NodeKind kind, String mimeType) Validate the value of an svn: property on file or directory and return a canonical representation of its value.
static byte[]	canonicalizeNodeProperty(String name, byte[] value, String path, NodeKind kind, String mimeType, InputStream fileContents) Validate the value of an svn: property on file or directory and return a canonical representation of its value.
static void	disableNativeCredentialsStore() Disable storing authentication credentials in Subversion's standard credentials store in the configuration directory and system-specific secure locations.
static void	enableNativeCredentialsStore() Enable storing authentication credentials in Subversion's standard credentials store in the configuration directory and system-specific secure locations.
static boolean	fileDiff(String originalFile, String modifiedFile, SVNUtil.DiffOptions diffOptions, String originalHeader, String modifiedHeader, String headerEncoding, String relativeToDir, OutputStream resultStream) Given two versions of a file, base (originalFile) and current (modifiedFile), show differences between them in unified diff format.
static boolean	fileMerge(String originalFile, String modifiedFile, String latestFile, SVNUtil.DiffOptions diffOptions, String conflictOriginal, String conflictModified, String conflictLatest, String conflictSeparator, SVNUtil.ConflictDisplayStyle conflictStyle, OutputStream resultStream) Given three versions of a file, base (originalFile), incoming (modifiedFile) and current (latestFile, produce a merged result, possibly displaying conflict markers.
static SVNUtil.Credential	getCredential(String configDir, SVNUtil.Credential.Kind kind, String realm) Find a stored credential.
static boolean	isNativeCredentialsStoreEnabled() Find out if the standard credentials store is enabled.
static List<ExternalItem>	parseExternals(byte[] description, String parentDirectory, boolean canonicalizeUrl) Parse description, assuming it is an externals specification in the format required for the svn:externals property, and return a list of parsed external items.
static SVNUtil.Credential	removeCredential(String configDir, SVNUtil.Credential.Kind kind, String realm) Remove a stored credential.
static String	resolveExternalsUrl(ExternalItem external, String reposRootUrl, String parentDirUrl) If the URL in external is relative, resolve it to an absolute URL, using reposRootUrl and parentDirUrl to provide contest.
static List<SVNUtil.Credential>	searchCredentials(String configDir, SVNUtil.Credential.Kind kind, String realmPattern, String usernamePattern, String hostnamePattern, String textPattern) Find stored credentials that match the given search criteria.
static InputStream	translateStream(InputStream source, byte[] eolMarker, boolean repairEol, boolean expandKeywords, byte[] keywordsValue, long revision, String url, String reposRootUrl, Date date, String author) Expand keywords and return a stream which performs end-of-line translation and keyword expansion when read from.
static InputStream	translateStream(InputStream source, byte[] eolMarker, boolean repairEol, Map<String,byte[]> keywords, boolean expandKeywords) Return a stream which performs end-of-line translation and keyword expansion when read from.
static OutputStream	translateStream(OutputStream destination, byte[] eolMarker, boolean repairEol, boolean expandKeywords, byte[] keywordsValue, long revision, String url, String reposRootUrl, Date date, String author) Expand keywords and return a stream which performs end-of-line translation and keyword expansion when written to.
static OutputStream	translateStream(OutputStream destination, byte[] eolMarker, boolean repairEol, Map<String,byte[]> keywords, boolean expandKeywords) Return a stream which performs end-of-line translation and keyword expansion when written to.
static byte[]	unparseExternals(List<ExternalItem> items, String parentDirectory) Unparse and list of external items into a format suitable for the value of the svn:externals property and validate the result.
static byte[]	unparseExternalsForAncientUnsupportedClients(List<ExternalItem> items, String parentDirectory) Unparse and list of external items into a format suitable for the value of the svn:externals property compatible with Subversion clients older than release 1.5, and validate the result.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EOL_LF

public static final byte[] EOL_LF

Use the linefeed code point ('\x0a') for the newline separator.

See Also:

translateStream, untranslateStream

EOL_CR

public static final byte[] EOL_CR

Use the carraige-return code point ('\x0d') for the newline separator.

See Also:

translateStream, untranslateStream

EOL_CRLF

public static final byte[] EOL_CRLF

Use carriage-return/linefeed sequence ('\x0d\x0a') for the newline separator.

See Also:

translateStream, untranslateStream

Constructor Detail

SVNUtil

public SVNUtil()

Method Detail

enableNativeCredentialsStore

public static void enableNativeCredentialsStore()
                                         throws ClientException

Enable storing authentication credentials in Subversion's standard credentials store in the configuration directory and system-specific secure locations.

The standard credentials store is enabled by default.

This setting will be inherited by all ISVNClient and ISVNRemote objects. Changing the setting will not affect existing such objects.

Throws:

ClientException

disableNativeCredentialsStore

public static void disableNativeCredentialsStore()
                                          throws ClientException

Disable storing authentication credentials in Subversion's standard credentials store in the configuration directory and system-specific secure locations. In this mode, the authentication (see ISVNClient.setPrompt(org.apache.subversion.javahl.callback.AuthnCallback) and RemoteFactory.setPrompt(org.apache.subversion.javahl.callback.AuthnCallback)) will be called every time the underlying library needs access to the credentials.

This mode is intented to support client implementations that use their own credentials store.

The standard credentials store is enabled by default.

This setting will be inherited by all ISVNClient and ISVNRemote objects. Changing the setting will not affect existing such objects.

Throws:

ClientException

isNativeCredentialsStoreEnabled

public static boolean isNativeCredentialsStoreEnabled()
                                               throws ClientException

Find out if the standard credentials store is enabled.

Throws:

ClientException

getCredential

public static SVNUtil.Credential getCredential(String configDir,
                                               SVNUtil.Credential.Kind kind,
                                               String realm)
                                        throws ClientException,
                                               SubversionException

Find a stored credential. Unlike searchCredentials(java.lang.String, org.apache.subversion.javahl.SVNUtil.Credential.Kind, java.lang.String, java.lang.String, java.lang.String, java.lang.String), the the realm name is not a glob pattern.

Note: If the native credentials store is disabled, this method will always return null.

Parameters:

configDir - The path to the configuration directory; if null, the default (system-specific) user configuration path will be used.

kind - The kind of the credential; may not be null.

realm - The realm name; may not be null.

Returns:

the matching credential, or null if not found.

Throws:

ClientException

SubversionException

removeCredential

public static SVNUtil.Credential removeCredential(String configDir,
                                                  SVNUtil.Credential.Kind kind,
                                                  String realm)
                                           throws ClientException,
                                                  SubversionException

Remove a stored credential. Unlike #deleteCredentials, the the realm name is not a glob pattern.

Note: If the native credentials store is disabled, this method will always return null.

Parameters:

configDir - The path to the configuration directory; if null, the default (system-specific) user configuration path will be used.

kind - The kind of the credential; may not be null.

realm - The realm name; may not be null.

Returns:

the deleted credential, or null if not found.

Throws:

ClientException

SubversionException

searchCredentials

public static List<SVNUtil.Credential> searchCredentials(String configDir,
                                                         SVNUtil.Credential.Kind kind,
                                                         String realmPattern,
                                                         String usernamePattern,
                                                         String hostnamePattern,
                                                         String textPattern)
                                                  throws ClientException,
                                                         SubversionException

Find stored credentials that match the given search criteria.

Note: If the native credentials store is disabled, this method will always return null.

Parameters:

configDir - The path to the configuration directory; if null, the default (system-specific) user configuration path will be used.

kind - The kind of the credential; if null, all matching credential types will be returned.

realmPattern - A glob pattern for the realm string; if null, all realms will be considered; otherwise, only those credentials whose realm matches the pattern will be returned.

usernamePattern - A glob pattern for the username; if null, all credentials will be considered; otherwise, only those credentials that have a username, and where the username matches the pattern, will be returned.

hostnamePattern - A glob pattern for the hostnames of a server certificate; if null, all credntials will be considered; otherwise, only those credentials that have a server certificate with a hostname that matches the pattern will be returned.

textPattern - A glob pattern that must match any textual information in a credential, for example, a realm, username, certificate details, etc; passwords, passphrases and other info considered secret will not be matched;

Returns:

the list of matching credentials.

Throws:

ClientException

SubversionException

fileDiff

public static boolean fileDiff(String originalFile,
                               String modifiedFile,
                               SVNUtil.DiffOptions diffOptions,
                               String originalHeader,
                               String modifiedHeader,
                               String headerEncoding,
                               String relativeToDir,
                               OutputStream resultStream)
                        throws ClientException

Given two versions of a file, base (originalFile) and current (modifiedFile), show differences between them in unified diff format.

Parameters:

originalFile - The base file version (unmodified)

modifiedFile - The incoming file version (locally modified)

diffOptions - Options controlling how files are compared. May be null.

originalHeader - The header to display for the base file in the unidiff index block. If it is null, the originalFile path and its modification time will be used instead.

modifiedHeader - The header to display for the current file in the unidiff index block. If it is null, the currentFile path and its modification time will be used instead.

headerEncoding - The character encoding of the unidiff headers.

relativeToDir - If this parameter is not , it must be the path of a (possibly non-immediate) parent of both originalFile and modifiedFile. This path will be stripped from the beginning of those file names if they are used in the unidiff index header.

resultStream - The stream that receives the merged output.

Returns:

true if there were differences between the files.

Throws:

ClientException

fileMerge

public static boolean fileMerge(String originalFile,
                                String modifiedFile,
                                String latestFile,
                                SVNUtil.DiffOptions diffOptions,
                                String conflictOriginal,
                                String conflictModified,
                                String conflictLatest,
                                String conflictSeparator,
                                SVNUtil.ConflictDisplayStyle conflictStyle,
                                OutputStream resultStream)
                         throws ClientException

Given three versions of a file, base (originalFile), incoming (modifiedFile) and current (latestFile, produce a merged result, possibly displaying conflict markers.

Parameters:

originalFile - The base file version (common ancestor)

modifiedFile - The incoming file version (modified elsewhere)

latestFile - The current file version (locally modified)

diffOptions - Options controlling how files are compared. May be null.

conflictOriginal - Optional custom conflict marker for the originalFile contents.

conflictModified - Optional custom conflict marker for the modifiedFile contents.

conflictLatest - Optional custom conflict marker for the latestFile contents.

conflictSeparator - Optional custom conflict separator.

conflictStyle - Determines how conflicts are displayed.

resultStream - The stream that receives the merged output.

Returns:

true if there were any conflicts.

Throws:

ClientException

canonicalizeNodeProperty

public static byte[] canonicalizeNodeProperty(String name,
                                              byte[] value,
                                              String path,
                                              NodeKind kind,
                                              String mimeType)
                                       throws ClientException

Validate the value of an svn: property on file or directory and return a canonical representation of its value.

Parameters:

name - The name of the property (must be a valid svn: property)

value - The property's value

path - The path or URL of the file or directory that owns the property; only used for error messages

kind - The node kind of the file or dir that owns the property

mimeType - If kind is NodeKind.file, this is tye file's mime-type, used for extra validation for the svn:eol-style property. If it is null, the extra validation will be skipped.

Returns:

a canonicalized representation of the property value

Throws:

ClientException

See Also:

http://subversion.apache.org/docs/api/latest/group__svn__wc__properties.html#ga83296313ec59cc825176224ac8282ec2

canonicalizeNodeProperty

public static byte[] canonicalizeNodeProperty(String name,
                                              byte[] value,
                                              String path,
                                              NodeKind kind,
                                              String mimeType,
                                              InputStream fileContents)
                                       throws ClientException

Validate the value of an svn: property on file or directory and return a canonical representation of its value.

Parameters:

name - The name of the property (must be a valid svn: property)

value - The property's value

path - The path or URL of the file or directory that owns the property; only used for error messages

kind - The node kind of the file or dir that owns the property

mimeType - If kind is NodeKind.file, this is tye file's mime-type, used for extra validation for the svn:eol-style property. If it is null, the extra validation will be skipped.

fileContents - A stream with the file's contents. Only used to check for line-ending consistency when validating the svn:eol-style property, and only when kind is NodeKind.file and mimeType is not null.

Returns:

a canonicalized representation of the property value

Throws:

ClientException

See Also:

http://subversion.apache.org/docs/api/latest/group__svn__wc__properties.html#ga83296313ec59cc825176224ac8282ec2

parseExternals

public static List<ExternalItem> parseExternals(byte[] description,
                                                String parentDirectory,
                                                boolean canonicalizeUrl)
                                         throws ClientException

Parse description, assuming it is an externals specification in the format required for the svn:externals property, and return a list of parsed external items.

Parameters:

description - The externals description.

parentDirectory - Used to construct error messages.

canonicalizeUrl - Whe true, canonicalize the url member of the returned objects. If the url member refers to an absolute URL, it will be canonicalized as URL consistent with the way URLs are canonicalized throughout the Subversion API. If, however, the url member makes use of the recognized (SVN-specific) relative URL syntax for svn:externals, "canonicalization" is an ill-defined concept which may even result in munging the relative URL syntax beyond recognition. You've been warned.

Returns:

a list of ExternalItems

Throws:

ClientException

unparseExternals

public static byte[] unparseExternals(List<ExternalItem> items,
                                      String parentDirectory)
                               throws SubversionException

Unparse and list of external items into a format suitable for the value of the svn:externals property and validate the result.

Parameters:

items - The list of ExternalItems

parentDirectory - Used to construct error messages.

compatibleWithSvn1_5 - When true, the format of the returned property value will be compatible with clients older than Subversion 1.5.

Throws:

SubversionException

unparseExternalsForAncientUnsupportedClients

public static byte[] unparseExternalsForAncientUnsupportedClients(List<ExternalItem> items,
                                                                  String parentDirectory)
                                                           throws SubversionException

Unparse and list of external items into a format suitable for the value of the svn:externals property compatible with Subversion clients older than release 1.5, and validate the result.

Parameters:

items - The list of ExternalItems

parentDirectory - Used to construct error messages.

Throws:

SubversionException

resolveExternalsUrl

public static String resolveExternalsUrl(ExternalItem external,
                                         String reposRootUrl,
                                         String parentDirUrl)
                                  throws ClientException

If the URL in external is relative, resolve it to an absolute URL, using reposRootUrl and parentDirUrl to provide contest.

Regardless if the URL is absolute or not, if there are no errors, the returned URL will be canonicalized.

The following relative URL formats are supported:

../

relative to the parent directory of the external

^/

relative to the repository root

//

relative to the scheme

/

relative to the server's hostname

The ../ and ^/ relative URLs may use .. to remove path elements up to the server root.

The external URL should not be canonicalized before calling this function, as otherwise the scheme relative URL '//host/some/path' would have been canonicalized to '/host/some/path' and we would not be able to match on the leading '//'.

Throws:

ClientException

buildKeywords

public static Map<String,byte[]> buildKeywords(byte[] keywordsValue,
                                               long revision,
                                               String url,
                                               String reposRootUrl,
                                               Date date,
                                               String author)
                                        throws SubversionException,
                                               ClientException

Build a dictionary of expanded keyword values, given the contents of a file's svn:keywords property, its revision, URL, the date it was committed on, the author of the commit and teh URL of the repository root.

Custom keywords defined in svn:keywords properties are expanded using the provided parameters and in accordance with the following format substitutions in the keywordsValue:

%a

The author.

%b

The basename of the URL.

%d

Short format of the date.

%D

Long format of the date.

%P

The file's path, relative to the repository root URL.

%r

The revision.

%R

The URL to the root of the repository.

%u

The URL of the file.

%_

A space (keyword definitions cannot contain a literal space).

%%

A literal '%'.

%H

Equivalent to %P%_%r%_%d%_%a.

%I

Equivalent to %b%_%r%_%d%_%a.

Custom keywords are defined by appending '=' to the keyword name, followed by a string containing any combination of the format substitutions.

Any of the revision, url, reposRootUrl, date and author parameters may be null, or Revision.SVN_INVALID_REVNUM for revision, to indicate that the information is not present. Each piece of information that is not present expands to the empty string wherever it appears in an expanded keyword value. (This can result in multiple adjacent spaces in the expansion of a multi-valued keyword such as "Id".)

Throws:

SubversionException

ClientException

translateStream

public static InputStream translateStream(InputStream source,
                                          byte[] eolMarker,
                                          boolean repairEol,
                                          Map<String,byte[]> keywords,
                                          boolean expandKeywords)
                                   throws SubversionException,
                                          ClientException

Return a stream which performs end-of-line translation and keyword expansion when read from.

Important: Make sure you close the returned stream to ensure all data are flushed and cleaned up (this will also close the provided stream and dispose the related netive object).

If eolMarker is not null, replace whatever any end-of-line sequences in the input with eolMarker. If the input has an inconsistent line ending style, then:

• if repairEol is false, then a subsequent read or other operation on the stream will generate an error when the inconsistency is detected;
• if repaorEol is true, convert any line ending to eolMarker.
  Recognized line endings are: "\n", "\r", and "\r\n".

Expand or contract keywords using the contents of keywords as the new values. If expandKeywords is true, expand contracted keywords and re-expand expanded keywords; otherwise, contract expanded keywords and ignore contracted ones. Keywords not found in the dictionary are ignored (not contracted or expanded). If the keywords itself is null, keyword substitution will be altogether ignored.

Detect only keywords that are no longer than SVN_KEYWORD_MAX_LEN bytes (currently: 255), including the delimiters and the keyword itself.

Recommendation: if expandKeywords is false, then you don't care about the keyword values, so just put null values into the keywords dictionary.

If the inner stream implements marking and seeking via InputStream.mark(int) and InputStream.reset(), the translated stream will too.

Parameters:

source - the source (untranslated) stream.

eolMarker - the byte sequence to use as the end-of-line marker; must be one of EOL_LF, EOL_CR or EOL_CRLF.

repairEol - flag to repair end-of-lines; see above

keywords - the keyword dictionary; see buildKeywords

expandKeywords - flag to expand keywords

Throws:

SubversionException

ClientException

translateStream

public static InputStream translateStream(InputStream source,
                                          byte[] eolMarker,
                                          boolean repairEol,
                                          boolean expandKeywords,
                                          byte[] keywordsValue,
                                          long revision,
                                          String url,
                                          String reposRootUrl,
                                          Date date,
                                          String author)
                                   throws SubversionException,
                                          ClientException

Expand keywords and return a stream which performs end-of-line translation and keyword expansion when read from.

Throws:

SubversionException

ClientException

See Also:

buildKeywords, translateStream(InputStream,byte[],boolean,Map,boolean)

translateStream

public static OutputStream translateStream(OutputStream destination,
                                           byte[] eolMarker,
                                           boolean repairEol,
                                           Map<String,byte[]> keywords,
                                           boolean expandKeywords)
                                    throws SubversionException,
                                           ClientException

Return a stream which performs end-of-line translation and keyword expansion when written to. Behaves like translateStream(InputStream,byte[],boolean,Map,boolean), except that it translates an OutputStream and never supports marking and seeking.

Throws:

SubversionException

ClientException

translateStream

public static OutputStream translateStream(OutputStream destination,
                                           byte[] eolMarker,
                                           boolean repairEol,
                                           boolean expandKeywords,
                                           byte[] keywordsValue,
                                           long revision,
                                           String url,
                                           String reposRootUrl,
                                           Date date,
                                           String author)
                                    throws SubversionException,
                                           ClientException

Expand keywords and return a stream which performs end-of-line translation and keyword expansion when written to.

Throws:

SubversionException

ClientException

See Also:

buildKeywords, translateStream(OutputStream,byte[],boolean,Map,boolean)