org.spearce.jgit/src/org/spearce/jgit/lib/Constants.java

   1 /*
   2  *  Copyright (C) 2006  Shawn Pearce <spearce@spearce.org>
   3  *
   4  *  This library is free software; you can redistribute it and/or
   5  *  modify it under the terms of the GNU General Public
   6  *  License, version 2, as published by the Free Software Foundation.
   7  *
   8  *  This library is distributed in the hope that it will be useful,
   9  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11  *  General Public License for more details.
  12  *
  13  *  You should have received a copy of the GNU General Public
  14  *  License along with this library; if not, write to the Free Software
  15  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
  16  */
  17 package org.spearce.jgit.lib;
  18
  19 import java.nio.charset.Charset;
  20 import java.security.MessageDigest;
  21 import java.security.NoSuchAlgorithmException;
  22
  23 /** Misc. constants used throughout JGit. */
  24 public final class Constants {
  25         /** Hash function used natively by Git for all objects. */
  26         private static final String HASH_FUNCTION = "SHA-1";
  27
  28         /** Length of an object hash. */
  29         public static final int OBJECT_ID_LENGTH = 20;
  30
  31         /** Special name for the "HEAD" symbolic-ref. */
  32         public static final String HEAD = "HEAD";
  33
  34         /**
  35          * Text string that identifies an object as a commit.
  36          * <p>
  37          * Commits connect trees into a string of project histories, where each
  38          * commit is an assertion that the best way to continue is to use this other
  39          * tree (set of files).
  40          */
  41         public static final String TYPE_COMMIT = "commit";
  42
  43         /**
  44          * Text string that identifies an object as a blob.
  45          * <p>
  46          * Blobs store whole file revisions. They are used for any user file, as
  47          * well as for symlinks. Blobs form the bulk of any project's storage space.
  48          */
  49         public static final String TYPE_BLOB = "blob";
  50
  51         /**
  52          * Text string that identifies an object as a tree.
  53          * <p>
  54          * Trees attach object ids (hashes) to names and file modes. The normal use
  55          * for a tree is to store a version of a directory and its contents.
  56          */
  57         public static final String TYPE_TREE = "tree";
  58
  59         /**
  60          * Text string that identifies an object as an annotated tag.
  61          * <p>
  62          * Annotated tags store a pointer to any other object, and an additional
  63          * message. It is most commonly used to record a stable release of the
  64          * project.
  65          */
  66         public static final String TYPE_TAG = "tag";
  67
  68         /** An unknown or invalid object type code. */
  69         public static final int OBJ_BAD = -1;
  70
  71         /**
  72          * In-pack object type: extended types.
  73          * <p>
  74          * This header code is reserved for future expansion. It is currently
  75          * undefined/unsupported.
  76          */
  77         public static final int OBJ_EXT = 0;
  78
  79         /**
  80          * In-pack object type: commit.
  81          * <p>
  82          * Indicates the associated object is a commit.
  83          * <p>
  84          * <b>This constant is fixed and is defined by the Git packfile format.</b>
  85          *
  86          * @see #TYPE_COMMIT
  87          */
  88         public static final int OBJ_COMMIT = 1;
  89
  90         /**
  91          * In-pack object type: tree.
  92          * <p>
  93          * Indicates the associated object is a tree.
  94          * <p>
  95          * <b>This constant is fixed and is defined by the Git packfile format.</b>
  96          *
  97          * @see #TYPE_BLOB
  98          */
  99         public static final int OBJ_TREE = 2;
 100
 101         /**
 102          * In-pack object type: blob.
 103          * <p>
 104          * Indicates the associated object is a blob.
 105          * <p>
 106          * <b>This constant is fixed and is defined by the Git packfile format.</b>
 107          *
 108          * @see #TYPE_BLOB
 109          */
 110         public static final int OBJ_BLOB = 3;
 111
 112         /**
 113          * In-pack object type: annotated tag.
 114          * <p>
 115          * Indicates the associated object is an annotated tag.
 116          * <p>
 117          * <b>This constant is fixed and is defined by the Git packfile format.</b>
 118          *
 119          * @see #TYPE_TAG
 120          */
 121         public static final int OBJ_TAG = 4;
 122
 123         /** In-pack object type: reserved for future use. */
 124         public static final int OBJ_TYPE_5 = 5;
 125
 126         /**
 127          * In-pack object type: offset delta
 128          * <p>
 129          * Objects stored with this type actually have a different type which must
 130          * be obtained from their delta base object. Delta objects store only the
 131          * changes needed to apply to the base object in order to recover the
 132          * original object.
 133          * <p>
 134          * An offset delta uses a negative offset from the start of this object to
 135          * refer to its delta base. The base object must exist in this packfile
 136          * (even in the case of a thin pack).
 137          * <p>
 138          * <b>This constant is fixed and is defined by the Git packfile format.</b>
 139          */
 140         public static final int OBJ_OFS_DELTA = 6;
 141
 142         /**
 143          * In-pack object type: reference delta
 144          * <p>
 145          * Objects stored with this type actually have a different type which must
 146          * be obtained from their delta base object. Delta objects store only the
 147          * changes needed to apply to the base object in order to recover the
 148          * original object.
 149          * <p>
 150          * A reference delta uses a full object id (hash) to reference the delta
 151          * base. The base object is allowed to be omitted from the packfile, but
 152          * only in the case of a thin pack being transferred over the network.
 153          * <p>
 154          * <b>This constant is fixed and is defined by the Git packfile format.</b>
 155          */
 156         public static final int OBJ_REF_DELTA = 7;
 157
 158         /** Native character encoding for commit messages, file names... */
 159         public static final String CHARACTER_ENCODING = "UTF-8";
 160
 161         /** Native character encoding for commit messages, file names... */
 162         public static final Charset CHARSET;
 163
 164         /** Default main branch name */
 165         public static final String MASTER = "master";
 166
 167         /** Prefix for branch refs */
 168         public static final String HEADS_PREFIX = "refs/heads";
 169
 170         /** Prefix for remotes refs */
 171         public static String REMOTES_PREFIX = "refs/remotes";
 172
 173         /**
 174          * Create a new digest function for objects.
 175          *
 176          * @return a new digest object.
 177          * @throws RuntimeException
 178          *             this Java virtual machine does not support the required hash
 179          *             function. Very unlikely given that JGit uses a hash function
 180          *             that is in the Java reference specification.
 181          */
 182         public static MessageDigest newMessageDigest() {
 183                 try {
 184                         return MessageDigest.getInstance(HASH_FUNCTION);
 185                 } catch (NoSuchAlgorithmException nsae) {
 186                         throw new RuntimeException("Required hash function "
 187                                         + HASH_FUNCTION + " not available.", nsae);
 188                 }
 189         }
 190
 191         /**
 192          * Convert an OBJ_* type constant to a TYPE_* type constant.
 193          *
 194          * @param typeCode the type code, from a pack representation.
 195          * @return the canonical string name of this type.
 196          */
 197         public static String typeString(final int typeCode) {
 198                 switch (typeCode) {
 199                 case OBJ_COMMIT:
 200                         return TYPE_COMMIT;
 201                 case OBJ_TREE:
 202                         return TYPE_TREE;
 203                 case OBJ_BLOB:
 204                         return TYPE_BLOB;
 205                 case OBJ_TAG:
 206                         return TYPE_TAG;
 207                 default:
 208                         throw new IllegalArgumentException("Bad object type: " + typeCode);
 209                 }
 210         }
 211
 212         /**
 213          * Convert an integer into its decimal representation.
 214          *
 215          * @param s
 216          *            the integer to convert.
 217          * @return a decimal representation of the input integer. The returned array
 218          *         is the smallest array that will hold the value.
 219          */
 220         public static byte[] encodeASCII(final long s) {
 221                 return encodeASCII(Long.toString(s));
 222         }
 223
 224         /**
 225          * Convert a string to US-ASCII encoding.
 226          *
 227          * @param s
 228          *            the string to convert. Must not contain any characters over
 229          *            127 (outside of 7-bit ASCII).
 230          * @return a byte array of the same length as the input string, holding the
 231          *         same characters, in the same order.
 232          * @throws IllegalArgumentException
 233          *             the input string contains one or more characters outside of
 234          *             the 7-bit ASCII character space.
 235          */
 236         public static byte[] encodeASCII(final String s) {
 237                 final byte[] r = new byte[s.length()];
 238                 for (int k = r.length - 1; k >= 0; k--) {
 239                         final char c = s.charAt(k);
 240                         if (c > 127)
 241                                 throw new IllegalArgumentException("Not ASCII string: " + s);
 242                         r[k] = (byte) c;
 243                 }
 244                 return r;
 245         }
 246
 247         static {
 248                 if (OBJECT_ID_LENGTH != newMessageDigest().getDigestLength())
 249                         throw new LinkageError("Incorrect OBJECT_ID_LENGTH.");
 250                 CHARSET = Charset.forName(CHARACTER_ENCODING);
 251         }
 252
 253         private Constants() {
 254                 // Hide the default constructor
 255         }
 256 }