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