/protocols/smpp/src/main/java/org/mobicents/protocols/smpp/message/tlv/TLVTable.java

  1/*
  2 * JBoss, Home of Professional Open Source
  3 * Copyright 2011, Red Hat, Inc. and individual contributors
  4 * by the @authors tag. See the copyright.txt in the distribution for a
  5 * full listing of individual contributors.
  6 *
  7 * This is free software; you can redistribute it and/or modify it
  8 * under the terms of the GNU Lesser General Public License as
  9 * published by the Free Software Foundation; either version 2.1 of
 10 * the License, or (at your option) any later version.
 11 *
 12 * This software is distributed in the hope that it will be useful,
 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 15 * Lesser General Public License for more details.
 16 *
 17 * You should have received a copy of the GNU Lesser General Public
 18 * License along with this software; if not, write to the Free
 19 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 20 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 21 */
 22
 23package org.mobicents.protocols.smpp.message.tlv;
 24
 25import java.io.IOException;
 26import java.util.BitSet;
 27import java.util.Map;
 28
 29import org.mobicents.protocols.smpp.util.PacketDecoder;
 30import org.mobicents.protocols.smpp.util.PacketEncoder;
 31
 32/**
 33 * Map of tag/length/value (TLV) parameters.
 34 * <p>
 35 * TLV stands for Tag/Length/Value and was a capability added to SMPP version
 36 * 3.4. It is an extensible means of adding new parameter types to SMPP packets.
 37 * Each optional parameter has a 2-byte tag, which is a unique identifier of
 38 * that parameter, a 2-byte length, which is an integer value representing the
 39 * length of the value of the parameter and a value. The value may be of various
 40 * types including integers, C Strings, octet strings, bit masks etc. The tag
 41 * defines the type of the value.
 42 * </p>
 43 * <p>
 44 * TLVs were originally called "optional parameters". SMPP v5 altered this
 45 * since it introduced the concept of required TLV parameters.
 46 * </p>
 47 * <p>
 48 * This class holds a mapping of tags to values. Each SMPP packet holds a TLV
 49 * table which holds that packet's set of current optional parameters. Upon
 50 * serializing the packet to an output stream or byte array, the format of the
 51 * serialized packet is:
 52 * </p>
 53 * 
 54 * <pre>
 55 * 
 56 *    +-------------------------+
 57 *    | SMPP Packet             |
 58 *    | +----------------------+|
 59 *    | | SMPP Header          ||
 60 *    | +----------------------+|
 61 *    | |                      ||
 62 *    | |                      ||
 63 *    | | Mandatory parameters ||
 64 *    | |                      ||
 65 *    | |                      ||
 66 *    | +----------------------+|
 67 *    | | Optional parameters  ||
 68 *    | | +------------------+ ||
 69 *    | | | Tag/Length/Value | ||
 70 *    | | +------------------+ ||
 71 *    | | |     ...          | ||
 72 *    | | +------------------+ ||
 73 *    | +----------------------+|
 74 *    +-------------------------+
 75 *  
 76 * </pre>
 77 * 
 78 * @version $Id: TLVTable.java 457 2009-01-15 17:37:42Z orank $
 79 */
 80public interface TLVTable extends Map<Tag, Object> {
 81    // TODO docs
 82    void readFrom(PacketDecoder decoder, int length);
 83    void writeTo(PacketEncoder encoder) throws IOException;
 84
 85    /**
 86     * Get the value for a tag. This is a convenience method to convert
 87     * the tag integer to its appropriate Tag object and then look that
 88     * tag up in the map.
 89     * @param tag The tag&apos;s integer value.
 90     */
 91    Object get(int tag);
 92
 93    /**
 94     * Get the tag&apos;s value as a string.
 95     * @param tag The tag to retrieve the value for.
 96     * @return The value as a string, or <code>null</code> if the specified
 97     * tag is not set in this table.
 98     */
 99    String getString(Tag tag);
100
101    /**
102     * Get the tag&apos;s value as an int.
103     * @param tag The tag to retrieve the value for.
104     * @return The value as an integer, or <code>-1</code> if the specified
105     * tag is not set in this table.
106     * @throws ClassCastException If the value for the specified tag is not
107     * a number (castable as a <code>java.lang.Number</code>).
108     */
109    int getInt(Tag tag);
110    
111    /**
112     * Get the tag&apos;s value as a long.
113     * @param tag The tag to retrieve the value for.
114     * @return The value as a long, or <code>-1</code> if the specified
115     * tag is not set in this table.
116     * @throws ClassCastException If the value for the specified tag is not
117     * a number (castable as a <code>java.lang.Number</code>).
118     */
119    long getLong(Tag tag);
120
121    /**
122     * Get the tag&apos;s value as a bit set.
123     * @param tag The tag to retrieve the value for.
124     * @return The value, cast as a <code>java.util.BitSet</code>, or
125     * <code>null</code> if the specified tag is not set in this table.
126     * @throws ClassCastException If the value for the specified tag is not
127     * a bit mask.
128     */
129    BitSet getBitmask(Tag tag);
130
131    /**
132     * Get the tag&apos;s value as a byte array.
133     * @param tag The tag to retrieve the value for.
134     * @return The value, cast as a <code>byte[]</code>, or <code>null</code>
135     * if the specified tag is not set in this table.
136     * @throws ClassCastException If the value for the specified tag is not
137     * a byte array.
138     */
139    byte[] getBytes(Tag tag);
140    
141    Object put(Tag tag, char value);
142    
143    Object put(Tag tag, short value);
144    
145    Object put(Tag tag, int value);
146    
147    Object put(Tag tag, long value);
148    
149    /**
150     * Remove (or un-set) a tag/value from this table.
151     * @param tag The tag to remove from the table.
152     */
153    void remove(int tag);
154    
155    /**
156     * Get the length the parameters in the table would encode as. The length of
157     * an SMPP packet is determined by: <br>
158     * <code>sizeof (smpp_header) + sizeof (mandatory_parameters)
159     * + sizeof (optional_parameters).</code>
160     * <br>
161     * The value returned for this method is the last clause in this equation.
162     * 
163     * @return The full length that the optional parameters would encode as.
164     */
165    int getLength();
166}