/protocols/smpp/src/main/java/org/mobicents/protocols/smpp/message/param/ParamDescriptor.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.param;
24
25import java.io.IOException;
26import java.io.OutputStream;
27import java.io.Serializable;
28
29import org.mobicents.protocols.smpp.util.PacketDecoder;
30import org.mobicents.protocols.smpp.util.PacketEncoder;
31
32/**
33 * Parameter descriptor. The parameter descriptor interface provides a way
34 * for SMPP types to be read from byte arrays and written to output streams.
35 * Descriptors are used for both mandatory and optional parameters.
36 * @version $Id: ParamDescriptor.java 457 2009-01-15 17:37:42Z orank $
37 */
38public interface ParamDescriptor extends Serializable {
39    /**
40     * Get the index of another numerical mandatory parameter which specifies
41     * the length of the parameter this descriptor represents. For example,
42     * in a submit_sm packet, the length of the short_message parameter is
43     * specified by the sm_length parameter, a 1-byte integer immediately
44     * preceding short_message in the mandatory parameter section of the packet.
45     * Therefore, the parameter descriptor that will be used to decode the
46     * short_message would return the index of the sm_length parameter in the
47     * body. This specified length can then be used to decode the correct
48     * number of bytes for the short message.
49     * <p>
50     * As another example, take the submit_multi packet. It has a mandatory
51     * parameter called dest_address(es) which specify all the destinations
52     * the message should be submitted to. The number of destinations in the
53     * destination table is specified by the number_of_dests mandatory
54     * parameter. In this case, the descriptor used to read the dest_addresses
55     * would return the index of number_of_dests from this method.
56     * </p>
57     * @return The index in the mandatory parameters of where to find the length
58     * specifier for this descriptor. If this descriptor does not need or
59     * support a length specifier, <code>-1</code> must be returned.
60     */
61    int getLengthSpecifier();
62
63    /**
64     * Get the encoded byte-size of <code>obj</code>.
65     * @param obj The object to calculate the encoded size for.
66     * @return The number of bytes the specified object would be encoded
67     * to via the {@link #writeObject(Object, OutputStream)} method.
68     */
69    int sizeOf(Object obj);
70
71    /**
72     * Write the specified object to an output stream.
73     * @param obj The object to encode.
74     * @param out The output stream to write the object to.
75     * @throws IOException If there was an error writing to the stream.
76     */
77    void writeObject(Object obj, PacketEncoder encoder) throws IOException;
78
79    /**
80     * Read an object from a byte array.
81     * @param data The byte data to read (or decode) an object from.
82     * @param position The position to begin parsing from. This position will
83     * be updated upon return to point to the first byte after the decoded
84     * object in the byte array.
85     * @param length The number of bytes to use in reading the object. If the
86     * length is unknown and intrinsic to the type being decoded (such as
87     * a C-String, which is terminated by a nul-byte), then <code>-1</code>
88     * may be supplied.
89     * @return The decoded object.
90     */
91    // TODO this should throw something - a runtime exception
92    Object readObject(PacketDecoder decoder, int length);
93}