Class TraceId

  • All Implemented Interfaces:
    java.lang.Comparable<TraceId>

    @Immutable
    public final class TraceId
    extends java.lang.Object
    implements java.lang.Comparable<TraceId>
    A class that represents a trace identifier. A valid trace identifier is a 16-byte array with at least one non-zero byte.
    Since:
    0.5
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static int BASE16_SIZE  
      private long idHi  
      private long idLo  
      static TraceId INVALID
      The invalid TraceId.
      private static long INVALID_ID  
      static int SIZE
      The size in bytes of the TraceId.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private TraceId​(long idHi, long idLo)  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(TraceId that)  
      void copyBytesTo​(byte[] dest, int destOffset)
      Copies the byte array representations of the TraceId into the dest beginning at the destOffset offset.
      void copyLowerBase16To​(char[] dest, int destOffset)
      Copies the lowercase base16 representations of the TraceId into the dest beginning at the destOffset offset.
      boolean equals​(java.lang.Object obj)  
      static TraceId fromBytes​(byte[] src)
      Returns a TraceId built from a byte representation.
      static TraceId fromBytes​(byte[] src, int srcOffset)
      Returns a TraceId whose representation is copied from the src beginning at the srcOffset offset.
      static TraceId fromLowerBase16​(java.lang.CharSequence src)
      Returns a TraceId built from a lowercase base16 representation.
      static TraceId fromLowerBase16​(java.lang.CharSequence src, int srcOffset)
      Returns a TraceId built from a lowercase base16 representation.
      static TraceId generateRandomId​(java.util.Random random)
      Generates a new random TraceId.
      byte[] getBytes()
      Returns the 16-bytes array representation of the TraceId.
      long getLowerLong()
      Returns the lower 8 bytes of the trace-id as a long value, assuming little-endian order.
      int hashCode()  
      boolean isValid()
      Returns whether the TraceId is valid.
      java.lang.String toLowerBase16()
      Returns the lowercase base16 encoding of this TraceId.
      java.lang.String toString()  
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • SIZE

        public static final int SIZE
        The size in bytes of the TraceId.
        Since:
        0.5
        See Also:
        Constant Field Values
      • INVALID

        public static final TraceId INVALID
        The invalid TraceId. All bytes are '\0'.
        Since:
        0.5
      • idHi

        private final long idHi
      • idLo

        private final long idLo
    • Constructor Detail

      • TraceId

        private TraceId​(long idHi,
                        long idLo)
    • Method Detail

      • fromBytes

        public static TraceId fromBytes​(byte[] src)
        Returns a TraceId built from a byte representation.
        Parameters:
        src - the representation of the TraceId.
        Returns:
        a TraceId whose representation is given by the src parameter.
        Throws:
        java.lang.NullPointerException - if src is null.
        java.lang.IllegalArgumentException - if src.length is not SIZE.
        Since:
        0.5
      • fromBytes

        public static TraceId fromBytes​(byte[] src,
                                        int srcOffset)
        Returns a TraceId whose representation is copied from the src beginning at the srcOffset offset.
        Parameters:
        src - the buffer where the representation of the TraceId is copied.
        srcOffset - the offset in the buffer where the representation of the TraceId begins.
        Returns:
        a TraceId whose representation is copied from the buffer.
        Throws:
        java.lang.NullPointerException - if src is null.
        java.lang.IndexOutOfBoundsException - if srcOffset+TraceId.SIZE is greater than src.length.
        Since:
        0.5
      • fromLowerBase16

        public static TraceId fromLowerBase16​(java.lang.CharSequence src)
        Returns a TraceId built from a lowercase base16 representation.
        Parameters:
        src - the lowercase base16 representation.
        Returns:
        a TraceId built from a lowercase base16 representation.
        Throws:
        java.lang.NullPointerException - if src is null.
        java.lang.IllegalArgumentException - if src.length is not 2 * TraceId.SIZE OR if the str has invalid characters.
        Since:
        0.11
      • fromLowerBase16

        public static TraceId fromLowerBase16​(java.lang.CharSequence src,
                                              int srcOffset)
        Returns a TraceId built from a lowercase base16 representation.
        Parameters:
        src - the lowercase base16 representation.
        srcOffset - the offset in the buffer where the representation of the TraceId begins.
        Returns:
        a TraceId built from a lowercase base16 representation.
        Throws:
        java.lang.NullPointerException - if src is null.
        java.lang.IllegalArgumentException - if not enough characters in the src from the srcOffset.
        Since:
        0.11
      • generateRandomId

        public static TraceId generateRandomId​(java.util.Random random)
        Generates a new random TraceId.
        Parameters:
        random - the random number generator.
        Returns:
        a new valid TraceId.
        Since:
        0.5
      • getBytes

        public byte[] getBytes()
        Returns the 16-bytes array representation of the TraceId.
        Returns:
        the 16-bytes array representation of the TraceId.
        Since:
        0.5
      • copyBytesTo

        public void copyBytesTo​(byte[] dest,
                                int destOffset)
        Copies the byte array representations of the TraceId into the dest beginning at the destOffset offset.
        Parameters:
        dest - the destination buffer.
        destOffset - the starting offset in the destination buffer.
        Throws:
        java.lang.NullPointerException - if dest is null.
        java.lang.IndexOutOfBoundsException - if destOffset+TraceId.SIZE is greater than dest.length.
        Since:
        0.5
      • copyLowerBase16To

        public void copyLowerBase16To​(char[] dest,
                                      int destOffset)
        Copies the lowercase base16 representations of the TraceId into the dest beginning at the destOffset offset.
        Parameters:
        dest - the destination buffer.
        destOffset - the starting offset in the destination buffer.
        Throws:
        java.lang.IndexOutOfBoundsException - if destOffset + 2 * TraceId.SIZE is greater than dest.length.
        Since:
        0.18
      • isValid

        public boolean isValid()
        Returns whether the TraceId is valid. A valid trace identifier is a 16-byte array with at least one non-zero byte.
        Returns:
        true if the TraceId is valid.
        Since:
        0.5
      • toLowerBase16

        public java.lang.String toLowerBase16()
        Returns the lowercase base16 encoding of this TraceId.
        Returns:
        the lowercase base16 encoding of this TraceId.
        Since:
        0.11
      • getLowerLong

        @Internal
        public long getLowerLong()
        Returns the lower 8 bytes of the trace-id as a long value, assuming little-endian order. This is used in ProbabilitySampler.

        This method is marked as internal and subject to change.

        Returns:
        the lower 8 bytes of the trace-id as a long value, assuming little-endian order.
      • equals

        public boolean equals​(@Nullable
                              java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • compareTo

        public int compareTo​(TraceId that)
        Specified by:
        compareTo in interface java.lang.Comparable<TraceId>