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.CTFException;
  19 import org.eclipse.tracecompass.ctf.core.event.io.BitBuffer;
  20 import org.eclipse.tracecompass.ctf.core.event.scope.IDefinitionScope;
  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     @Override
 112     public int getMaximumSize() {
 113         /*
 114          * Every definition can have a different size, so we do not scope this.
 115          * Minimum size is one byte (8 bits) though.
 116          */
 117         return 8;
 118     }
 119
 120     // ------------------------------------------------------------------------
 121     // Operations
 122     // ------------------------------------------------------------------------
 123
 124     @Override
 125     public StringDefinition createDefinition(@Nullable IDefinitionScope definitionScope,
 126             String fieldName, BitBuffer input) throws CTFException {
 127         String value = read(input);
 128         return new StringDefinition(this, definitionScope, fieldName, value);
 129     }
 130
 131     private String read(BitBuffer input) throws CTFException {
 132         /* Offset the buffer position wrt the current alignment */
 133         alignRead(input);
 134
 135         StringBuilder sb = new StringBuilder();
 136         char c = (char) input.get(BITS_PER_BYTE, false);
 137         while (c != 0) {
 138             sb.append(c);
 139             c = (char) input.get(BITS_PER_BYTE, false);
 140         }
 141         return NonNullUtils.checkNotNull(sb.toString());
 142     }
 143
 144     @Override
 145     public String toString() {
 146         /* Only used for debugging */
 147         return "[declaration] string[" + Integer.toHexString(hashCode()) + ']'; //$NON-NLS-1$
 148     }
 149
 150     @Override
 151     public int hashCode() {
 152         final int prime = 31;
 153         int result = prime;
 154         switch (fEncoding) {
 155         case ASCII:
 156             result += 1;
 157             break;
 158         case NONE:
 159             result += 2;
 160             break;
 161         case UTF8:
 162             result += 3;
 163             break;
 164         default:
 165             break;
 166         }
 167         return result;
 168     }
 169
 170     @Override
 171     public boolean equals(@Nullable Object obj) {
 172         if (this == obj) {
 173             return true;
 174         }
 175         if (obj == null) {
 176             return false;
 177         }
 178         if (getClass() != obj.getClass()) {
 179             return false;
 180         }
 181         StringDeclaration other = (StringDeclaration) obj;
 182         if (fEncoding != other.fEncoding) {
 183             return false;
 184         }
 185         return true;
 186     }
 187
 188     @Override
 189     public boolean isBinaryEquivalent(@Nullable IDeclaration other) {
 190         return equals(other);
 191     }
 192
 193 }