Package org.apache.subversion.javahl

Class SVNUtil

java.lang.Object
org.apache.subversion.javahl.SVNUtil
public class SVNUtil
extends Object

  • Field Details

  • Constructor Details

  • Method Details

    • 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 remote.RemoteFactory#setPrompt) 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

    • 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

    • 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(byte[],long,java.lang.String,java.lang.String,java.util.Date,java.lang.String)
      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(byte[],long,java.lang.String,java.lang.String,java.util.Date,java.lang.String), translateStream(java.io.InputStream,byte[],boolean,java.util.Map<java.lang.String,byte[]>,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(byte[],long,java.lang.String,java.lang.String,java.util.Date,java.lang.String), translateStream(java.io.OutputStream,byte[],boolean,java.util.Map<java.lang.String,byte[]>,boolean)