bytedata.java

Logica lastest SMPP API

/*
 * Copyright (c) 1996-2001
 * Logica Mobile Networks Limited
 * All rights reserved.
 *
 * This software is distributed under Logica Open Source License Version 1.0
 * ("Licence Agreement"). You shall use it and distribute only in accordance
 * with the terms of the License Agreement.
 *
 */
package com.logica.smpp.pdu;

import java.io.UnsupportedEncodingException;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Date;

import com.logica.smpp.Data;
import com.logica.smpp.SmppObject;
import com.logica.smpp.pdu.tlv.TLV;
import com.logica.smpp.util.ByteBuffer;
import com.logica.smpp.util.NotEnoughDataInByteBufferException;
import com.logica.smpp.util.TerminatingZeroNotFoundException;

/**
 * Base class for all object which can be transformed to sequence of bytes
 * and which can be re-read from sequence of bytes. The sequence of bytes
 * is represented by <code>ByteBuffer</code>.
 * Every descendant of this class must implement <code>setData</code> and
 * <code>getData</code> functions.
 * Apart from abstract methods this class contains static methods for checking
 * of validity of certain values like if the length of string is
 * within valid boundary, if the date format is valid etc.
 *
 * @author Logica Mobile Networks SMPP Open Source Team
 * @version 1.2, 20 Nov 2001
 * @see #setData(ByteBuffer)
 * @see #getData()
 */

/*
  13-07-01 [e-mail] indentation fixed, tabs aren't used anymore
  03-10-01 [e-mail] string passed as a parameter to the string length
                           checking routines is now checked first if it's not null
  03-10-01 [e-mail] the datetime string format is fully checked
                           in the function checkDate according to the date format
                           spec in smpp
  31-10-01 [e-mail] added methods for correction from 'smaller' int negative
                           to 'bigger' int positive (for variables carrying lengths)
                           (several times reported this, thanks!)
  15-11-01 [e-mail] added support for checking length of data produced
                           from string with multibyte encoding
  16-11-01 [e-mail] added method for checking if length provided as int
                           is within provided bounds
  20-11-01 [e-mail] fixed date checking where relative dates were
                           rejected as incorrect; now relative dates are checked
                           only partially
*/
public abstract class ByteData extends SmppObject
{
    /**
     * Defines a format of part of the smpp defined date format
     * which is parseable by Java SimpleDateFormat parser.
     * The rest (nnp) is parsed 'manually'.
     */
    private static final String SMPP_TIME_DATE_FORMAT = "yyMMddHHmmss";

    /**
     * The formatter object used for checking if the format of the datetime
     * string is correct.
     */
    private static SimpleDateFormat dateFormatter;

    /**
     * Controls checking of the date-time format in the library.
     * If this variable to is set to <code>true</code> the library will check if
     * the date is correctly formated according SMPP spec; if it's
     * <code>false</code>, then the date will be sent without checking in
     * the library and the check will be done by the SMSC. Default
     * is <code>true</code>.
     * Note that whatever is the setting, the library will still check
     * the length of the date-time string.
     */
    private static boolean libraryCheckDateFormat = true;

    /**
     * Static initialiser initialises the <code>dateFormatter</code>
     * with format specified for SMPP Date/Time format and sets
     * other formatter parameters.
     */
    static {
        dateFormatter = new SimpleDateFormat(SMPP_TIME_DATE_FORMAT);
        dateFormatter.setLenient(false);
    }

     /**
     * This abstract method should parse the buffer with binary data
     * passed as parameter into member variables.
     *
     * @param buffer the data which should contain binary representation of
     *               the class
     * @see #getData()
     * @throws PDUException some data in the buffer were invalid
     * @throws NotEnoughDataInByteBufferException expected more data in
               the buffer
     * @throws TerminatingZeroNotFoundException the c-string in buffer
     *         wasn't terminated with 0  zero
     */
    public abstract void setData(ByteBuffer buffer)
    throws PDUException,
           NotEnoughDataInByteBufferException,
           TerminatingZeroNotFoundException;

     /**
     * This abstract method should create a binary buffer from it's member
     * variables.
     *
     * @return the binary data buffer created from member variables
     * @see #setData(ByteBuffer)
     * @throws ValueNotSetException thrown from a TLV if the value was
     *         requested but never set
     * @see TLV
     * @see ValueNotSetException
     */
    public abstract ByteBuffer getData()
    throws ValueNotSetException;

    /**
     * Default constructor. Only this is present as this
     * abstract class doesn't have any member variables.
     */
    public ByteData()
    {
    }

    /**
     * Checks if the length of string is less or equal than the provided
     * maximum.
     *
     * @param string the string to check
     * @param max    the maximal length of the string
     * @exception WrongLengthOfStringException thrown if the string is longer
     *            than the provided max length
     */
    protected static void checkString(String string, int max)
    throws WrongLengthOfStringException
    {
        checkString(string,0,max);
    }
    
    /**
     * Checks if the length of the data of the string is less or equal than
     * the provided maximum; necessery for multibyte encodings. 
     * Note that the length checked is the length wfter transforming
     * the string to series of octets, so two-byte strings will efectively
     * require space (max size) two-times the length of the string.
     * @param string the string to check
     * @param max    the maximal length of the string
     * @param encoding the encoding of the string
     * @exception WrongLengthOfStringException thrown if the string is longer
     *            than the provided max length
     * @exception UnsupportedEncodingException the required encoding isn't
     *            supported
     */
    protected static void checkString(String string, int max, String encoding)
    throws WrongLengthOfStringException,
           UnsupportedEncodingException
    {
        checkString(string,0,max,encoding);
    }
    
    /**
     * Checks if the length of string is greater or equal than provided
     * minimum and less or equal than the provided maximum.
     *
     * @param string the string to check
     * @param min    the minimal length of the string
     * @param max    the maximal length of the string
     * @throws WrongLengthOfStringException thrown if the string is shorter
     *         than min length or longer than max length
     */
    protected static void checkString(String string, int min, int max)
    throws WrongLengthOfStringException
    {
        int length = string==null ? 0 : string.length();
        checkString(min,length,max);
    }
    
    /**
     * Checks if the length of the data of the string is greater or equal
     * than provided minimum and less or equal than the provided maximum;
     * necessery for multibyte encodings.
     *
     * @param string the string to check
     * @param min    the minimal length of the string
     * @param max    the maximal length of the string
     * @param encoding the encoding of the string
     * @throws WrongLengthOfStringException thrown if the string is shorter
     *         than min length or longer than max length
     * @exception UnsupportedEncodingException the required encoding isn't
     *            supported
     */
    protected static void checkString(String string, int min, int max,
                                      String encoding)
    throws WrongLengthOfStringException,
           UnsupportedEncodingException
    {
        byte[] stringBytes = string.getBytes(encoding);
        int length = stringBytes==null ? 0 : stringBytes.length;
        checkString(min,length,max);
    }
    
    /**
     * Checks if the integer value representing length is within provided valid
     * length.
     *
     * @param min minimal possible length
     * @param val the length to check
     * @param max maximal possible length