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         private static final byte[] ENCODED_TYPE_COMMIT = encodeASCII(TYPE_COMMIT);
  69
  70         private static final byte[] ENCODED_TYPE_BLOB = encodeASCII(TYPE_BLOB);
  71
  72         private static final byte[] ENCODED_TYPE_TREE = encodeASCII(TYPE_TREE);
  73
  74         private static final byte[] ENCODED_TYPE_TAG = encodeASCII(TYPE_TAG);
  75
  76         /** An unknown or invalid object type code. */
  77         public static final int OBJ_BAD = -1;
  78
  79         /**
  80          * In-pack object type: extended types.
  81          * <p>
  82          * This header code is reserved for future expansion. It is currently
  83          * undefined/unsupported.
  84          */
  85         public static final int OBJ_EXT = 0;
  86
  87         /**
  88          * In-pack object type: commit.
  89          * <p>
  90          * Indicates the associated object is a commit.
  91          * <p>
  92          * <b>This constant is fixed and is defined by the Git packfile format.</b>
  93          *
  94          * @see #TYPE_COMMIT
  95          */
  96         public static final int OBJ_COMMIT = 1;
  97
  98         /**
  99          * In-pack object type: tree.
 100          * <p>
 101          * Indicates the associated object is a tree.
 102          * <p>
 103          * <b>This constant is fixed and is defined by the Git packfile format.</b>
 104          *
 105          * @see #TYPE_BLOB
 106          */
 107         public static final int OBJ_TREE = 2;
 108
 109         /**
 110          * In-pack object type: blob.
 111          * <p>
 112          * Indicates the associated object is a blob.
 113          * <p>
 114          * <b>This constant is fixed and is defined by the Git packfile format.</b>
 115          *
 116          * @see #TYPE_BLOB
 117          */
 118         public static final int OBJ_BLOB = 3;
 119
 120         /**
 121          * In-pack object type: annotated tag.
 122          * <p>
 123          * Indicates the associated object is an annotated tag.
 124          * <p>
 125          * <b>This constant is fixed and is defined by the Git packfile format.</b>
 126          *
 127          * @see #TYPE_TAG
 128          */
 129         public static final int OBJ_TAG = 4;
 130
 131         /** In-pack object type: reserved for future use. */
 132         public static final int OBJ_TYPE_5 = 5;
 133
 134         /**
 135          * In-pack object type: offset delta
 136          * <p>
 137          * Objects stored with this type actually have a different type which must
 138          * be obtained from their delta base object. Delta objects store only the
 139          * changes needed to apply to the base object in order to recover the
 140          * original object.
 141          * <p>
 142          * An offset delta uses a negative offset from the start of this object to
 143          * refer to its delta base. The base object must exist in this packfile
 144          * (even in the case of a thin pack).
 145          * <p>
 146          * <b>This constant is fixed and is defined by the Git packfile format.</b>
 147          */
 148         public static final int OBJ_OFS_DELTA = 6;
 149
 150         /**
 151          * In-pack object type: reference delta
 152          * <p>
 153          * Objects stored with this type actually have a different type which must
 154          * be obtained from their delta base object. Delta objects store only the
 155          * changes needed to apply to the base object in order to recover the
 156          * original object.
 157          * <p>
 158          * A reference delta uses a full object id (hash) to reference the delta
 159          * base. The base object is allowed to be omitted from the packfile, but
 160          * only in the case of a thin pack being transferred over the network.
 161          * <p>
 162          * <b>This constant is fixed and is defined by the Git packfile format.</b>
 163          */
 164         public static final int OBJ_REF_DELTA = 7;
 165
 166         /** Native character encoding for commit messages, file names... */
 167         public static final String CHARACTER_ENCODING = "UTF-8";
 168
 169         /** Native character encoding for commit messages, file names... */
 170         public static final Charset CHARSET;
 171
 172         /** Default main branch name */
 173         public static final String MASTER = "master";
 174
 175         /** Prefix for branch refs */
 176         public static final String HEADS_PREFIX = "refs/heads";
 177
 178         /** Prefix for remotes refs */
 179         public static final String REMOTES_PREFIX = "refs/remotes";
 180
 181         /** Prefix for tag refs */
 182         public static final String TAGS_PREFIX = "refs/tags";
 183
 184         /**
 185          * Create a new digest function for objects.
 186          *
 187          * @return a new digest object.
 188          * @throws RuntimeException
 189          *             this Java virtual machine does not support the required hash
 190          *             function. Very unlikely given that JGit uses a hash function
 191          *             that is in the Java reference specification.
 192          */
 193         public static MessageDigest newMessageDigest() {
 194                 try {
 195                         return MessageDigest.getInstance(HASH_FUNCTION);
 196                 } catch (NoSuchAlgorithmException nsae) {
 197                         throw new RuntimeException("Required hash function "
 198                                         + HASH_FUNCTION + " not available.", nsae);
 199                 }
 200         }
 201
 202         /**
 203          * Convert an OBJ_* type constant to a TYPE_* type constant.
 204          *
 205          * @param typeCode the type code, from a pack representation.
 206          * @return the canonical string name of this type.
 207          */
 208         public static String typeString(final int typeCode) {
 209                 switch (typeCode) {
 210                 case OBJ_COMMIT:
 211                         return TYPE_COMMIT;
 212                 case OBJ_TREE:
 213                         return TYPE_TREE;
 214                 case OBJ_BLOB:
 215                         return TYPE_BLOB;
 216                 case OBJ_TAG:
 217                         return TYPE_TAG;
 218                 default:
 219                         throw new IllegalArgumentException("Bad object type: " + typeCode);
 220                 }
 221         }
 222
 223         /**
 224          * Convert an OBJ_* type constant to an ASCII encoded string constant.
 225          * <p>
 226          * The ASCII encoded string is often the canonical representation of
 227          * the type within a loose object header, or within a tag header.
 228          *
 229          * @param typeCode the type code, from a pack representation.
 230          * @return the canonical ASCII encoded name of this type.
 231          */
 232         public static byte[] encodedTypeString(final int typeCode) {
 233                 switch (typeCode) {
 234                 case OBJ_COMMIT:
 235                         return ENCODED_TYPE_COMMIT;
 236                 case OBJ_TREE:
 237                         return ENCODED_TYPE_TREE;
 238                 case OBJ_BLOB:
 239                         return ENCODED_TYPE_BLOB;
 240                 case OBJ_TAG:
 241                         return ENCODED_TYPE_TAG;
 242                 default:
 243                         throw new IllegalArgumentException("Bad object type: " + typeCode);
 244                 }
 245         }
 246
 247         /**
 248          * Convert an integer into its decimal representation.
 249          *
 250          * @param s
 251          *            the integer to convert.
 252          * @return a decimal representation of the input integer. The returned array
 253          *         is the smallest array that will hold the value.
 254          */
 255         public static byte[] encodeASCII(final long s) {
 256                 return encodeASCII(Long.toString(s));
 257         }
 258
 259         /**
 260          * Convert a string to US-ASCII encoding.
 261          *
 262          * @param s
 263          *            the string to convert. Must not contain any characters over
 264          *            127 (outside of 7-bit ASCII).
 265          * @return a byte array of the same length as the input string, holding the
 266          *         same characters, in the same order.
 267          * @throws IllegalArgumentException
 268          *             the input string contains one or more characters outside of
 269          *             the 7-bit ASCII character space.
 270          */
 271         public static byte[] encodeASCII(final String s) {
 272                 final byte[] r = new byte[s.length()];
 273                 for (int k = r.length - 1; k >= 0; k--) {
 274                         final char c = s.charAt(k);
 275                         if (c > 127)
 276                                 throw new IllegalArgumentException("Not ASCII string: " + s);
 277                         r[k] = (byte) c;
 278                 }
 279                 return r;
 280         }
 281
 282         static {
 283                 if (OBJECT_ID_LENGTH != newMessageDigest().getDigestLength())
 284                         throw new LinkageError("Incorrect OBJECT_ID_LENGTH.");
 285                 CHARSET = Charset.forName(CHARACTER_ENCODING);
 286         }
 287
 288         private Constants() {
 289                 // Hide the default constructor
 290         }
 291 }