org.eclipse.tracecompass.ctf.core/src/org/eclipse/tracecompass/ctf/core/event/types/StringDeclaration.java

   1 /*******************************************************************************
   2  * Copyright (c) 2011, 2014 Ericsson, Ecole Polytechnique de Montreal and others
   3  *
   4  * All rights reserved. This program and the accompanying materials are made
   5  * available under the terms of the Eclipse Public License v1.0 which
   6  * accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *
   9  * Contributors: Matthew Khouzam - Initial API and implementation
  10  * Contributors: Simon Marchi - Initial API and implementation
  11  *******************************************************************************/
  12
  13 package org.eclipse.tracecompass.ctf.core.event.types;
  14
  15 import org.eclipse.jdt.annotation.NonNullByDefault;
  16 import org.eclipse.jdt.annotation.Nullable;
  17 import org.eclipse.tracecompass.common.core.NonNullUtils;
  18 import org.eclipse.tracecompass.ctf.core.event.io.BitBuffer;
  19 import org.eclipse.tracecompass.ctf.core.event.scope.IDefinitionScope;
  20 import org.eclipse.tracecompass.ctf.core.trace.CTFReaderException;
  21
  22 /**
  23  * A CTF string declaration.
  24  *
  25  * Strings are an array of bytes of variable size and are terminated by a '\0'
  26  * "NULL" character. Their encoding is described in the TSDL meta-data. In
  27  * absence of encoding attribute information, the default encoding is UTF-8.
  28  *
  29  * @version 1.0
  30  * @author Matthew Khouzam
  31  * @author Simon Marchi
  32  */
  33 @NonNullByDefault
  34 public class StringDeclaration extends Declaration {
  35
  36     private static final StringDeclaration STRING_DEC_UTF8 = new StringDeclaration(Encoding.UTF8);
  37     private static final StringDeclaration STRING_DEC_ASCII = new StringDeclaration(Encoding.ASCII);
  38     private static final StringDeclaration STRING_DEC_NO_ENC = new StringDeclaration(Encoding.NONE);
  39
  40     // ------------------------------------------------------------------------
  41     // Attributes
  42     // ------------------------------------------------------------------------
  43
  44     private static final int BITS_PER_BYTE = Byte.SIZE;
  45     private final Encoding fEncoding;
  46
  47     // ------------------------------------------------------------------------
  48     // Constructors
  49     // ------------------------------------------------------------------------
  50
  51     /**
  52      * Generate an encoded string declaration
  53      *
  54      * @param encoding
  55      *            the encoding, utf8 or ascii
  56      */
  57     private StringDeclaration(Encoding encoding) {
  58         fEncoding = encoding;
  59     }
  60
  61     /**
  62      * Create a StringDeclaration with the default UTF-8 encoding
  63      *
  64      * @return a {@link StringDeclaration} with UTF-8 encoding
  65      */
  66     public static StringDeclaration getStringDeclaration() {
  67         return STRING_DEC_UTF8;
  68     }
  69
  70     /**
  71      * Create a StringDeclaration
  72      *
  73      * @param encoding
  74      *            the {@link Encoding} can be Encoding.UTF8, Encoding.ASCII or
  75      *            other
  76      * @return a {@link StringDeclaration}
  77      * @throws IllegalArgumentException
  78      *             if the encoding is not recognized.
  79      */
  80     public static StringDeclaration getStringDeclaration(Encoding encoding) {
  81         switch (encoding) {
  82         case ASCII:
  83             return STRING_DEC_ASCII;
  84         case NONE:
  85             return STRING_DEC_NO_ENC;
  86         case UTF8:
  87             return STRING_DEC_UTF8;
  88         default:
  89             throw new IllegalArgumentException("Unrecognized encoding: " + encoding); //$NON-NLS-1$
  90         }
  91     }
  92
  93     // ------------------------------------------------------------------------
  94     // Getters/Setters/Predicates
  95     // ------------------------------------------------------------------------
  96
  97     /**
  98      *
  99      * @return the character encoding.
 100      */
 101     public Encoding getEncoding() {
 102         return fEncoding;
 103     }
 104
 105     @Override
 106     public long getAlignment() {
 107         // See ctf 4.2.5: Strings are always aligned on byte size.
 108         return BITS_PER_BYTE;
 109     }
 110
 111     /**
 112      * @since 3.0
 113      */
 114     @Override
 115     public int getMaximumSize() {
 116         return Integer.MAX_VALUE;
 117     }
 118
 119     // ------------------------------------------------------------------------
 120     // Operations
 121     // ------------------------------------------------------------------------
 122
 123     /**
 124      * @since 3.0
 125      */
 126     @Override
 127     public StringDefinition createDefinition(@Nullable IDefinitionScope definitionScope,
 128             String fieldName, BitBuffer input) throws CTFReaderException {
 129         String value = read(input);
 130         return new StringDefinition(this, definitionScope, fieldName, value);
 131     }
 132
 133     private String read(BitBuffer input) throws CTFReaderException {
 134         /* Offset the buffer position wrt the current alignment */
 135         alignRead(input);
 136
 137         StringBuilder sb = new StringBuilder();
 138         char c = (char) input.get(BITS_PER_BYTE, false);
 139         while (c != 0) {
 140             sb.append(c);
 141             c = (char) input.get(BITS_PER_BYTE, false);
 142         }
 143         return NonNullUtils.checkNotNull(sb.toString());
 144     }
 145
 146     @Override
 147     public String toString() {
 148         /* Only used for debugging */
 149         return "[declaration] string[" + Integer.toHexString(hashCode()) + ']'; //$NON-NLS-1$
 150     }
 151
 152     @Override
 153     public int hashCode() {
 154         final int prime = 31;
 155         int result = prime;
 156         switch (fEncoding) {
 157         case ASCII:
 158             result += 1;
 159             break;
 160         case NONE:
 161             result += 2;
 162             break;
 163         case UTF8:
 164             result += 3;
 165             break;
 166         default:
 167             break;
 168         }
 169         return result;
 170     }
 171
 172     @Override
 173     public boolean equals(@Nullable Object obj) {
 174         if (this == obj) {
 175             return true;
 176         }
 177         if (obj == null) {
 178             return false;
 179         }
 180         if (getClass() != obj.getClass()) {
 181             return false;
 182         }
 183         StringDeclaration other = (StringDeclaration) obj;
 184         if (fEncoding != other.fEncoding) {
 185             return false;
 186         }
 187         return true;
 188     }
 189
 190     @Override
 191     public boolean isBinaryEquivalent(@Nullable IDeclaration other) {
 192         return equals(other);
 193     }
 194
 195 }