session.java

Short Message Peer to Peer

		return (CancelSMResp) send(request);
	}

	/**
	 * Replaces previously submitted message by sending <code>ReplaceSM</code>
	 * PDU to SMSC and returns response to the replace.
	 * <p>
	 * See "SMPP Protocol Specification 3.4, 4.10 REPLACE_SM Operation."
	 *
	 * @param   request   the replace pdu to be sent
	 * @return            correspondent response pdu
	 *
	 * @exception IOException exception during communication
	 * @exception PDUException incorrect format of PDU
	 * @exception TimeoutException rest of data not received for too long time
	 * @exception ValueNotSetException optional param not set but requested
	 * @see ReplaceSM
	 * @see ReplaceSMResp
	 */
	final public ReplaceSMResp replace(ReplaceSM request)
		throws ValueNotSetException, TimeoutException, PDUException, IOException, WrongSessionStateException {
		checkState(request);
		return (ReplaceSMResp) send(request);
	}

	/**
	 * Checks the status of connection between ESME and SMSC by sending
	 * <code>EnquireLink</code> PDU to SMSC; returns response 
	 * to the enquiry.
	 * <p>
	 * See "SMPP Protocol Specification 3.4, 4.11 ENQUIRE_LINK Operation."
	 *
	 * @param   request   the enquiry pdu to be submitted
	 * @return            correspondent response pdu
	 *
	 * @exception IOException exception during communication
	 * @exception PDUException incorrect format of PDU
	 * @exception TimeoutException rest of data not received for too long time
	 * @exception ValueNotSetException optional param not set but requested
	 * @see EnquireLink
	 * @see EnquireLinkResp
	 */
	final public EnquireLinkResp enquireLink(EnquireLink request)
		throws ValueNotSetException, TimeoutException, PDUException, IOException, WrongSessionStateException {
		checkState(request);
		return (EnquireLinkResp) send(request);
	}

	/**
	 * Simplified veriosn of <a href="#enquireLink(EnquireLink)">enquireLink</a>.
	 * As the <code>EnquireLink</code> PDU doesn't contain any parameters
	 * axcept of header, there is might be no need to provide the PDU as
	 * a parameter to the <code>enquireLink</code> method.<br>
	 * This method creates new <code>EnquireLink</code> object
	 * and sends it to SMSC; returns response to the enquiry.
	 * <p>
	 * See "SMPP Protocol Specification 3.4, 4.11 ENQUIRE_LINK Operation."
	 *
	 * @return            correspondent response pdu
	 *
	 * @exception IOException exception during communication
	 * @exception PDUException incorrect format of PDU
	 * @exception TimeoutException rest of data not received for too long time
	 * @exception ValueNotSetException optional param not set but requested
	 * @see EnquireLink
	 * @see EnquireLinkResp
	 */
	final public EnquireLinkResp enquireLink()
		throws ValueNotSetException, TimeoutException, PDUException, IOException, WrongSessionStateException {
		EnquireLink request = new EnquireLink();
		checkState(request);
		return enquireLink(request);
	}

	/**
	 * Submits provided <code>SubmitSM</code> PDU to SMSC and returns response to the submission.
	 * <p>
	 * See "SMPP Protocol Specification 3.4, 4.12 ALERT_NOTIFICATION Operation."
	 *
	 * @param   request   the pdu to be submitted
	 *
	 * @exception IOException exception during communication
	 * @exception PDUException incorrect format of PDU
	 * @exception TimeoutException rest of data not received for too long time
	 * @exception ValueNotSetException optional param not set but requested
	 * @see AlertNotification
	 */
	final public void alertNotification(AlertNotification request)
		throws ValueNotSetException, TimeoutException, PDUException, IOException, WrongSessionStateException {
		checkState(request);
		send(request);
	}

	/**
	 * Returns a PDU received from SMSC. This is blocking receive, caller
	 * will wait until a PDU will be received.<br>
	 * Note that this method can be called only when bound as receiver
	 * or transciever.
	 *
	 * @return received pdu
	 * 
	 * @exception IOException exception during communication
	 * @exception NotSynchronousException receive called in asynchronous mode
	 * @exception PDUException incorrect format of PDU
	 * @exception TimeoutException rest of data not received for too long time
	 * @exception UnknownCommandIdException PDU with unknown id was received
	 * @see Receiver
	 * @see ReceiverBase
	 */
	final public PDU receive()
		throws UnknownCommandIdException, TimeoutException, NotSynchronousException, PDUException, IOException {
		if (!asynchronous) {
			return receive(Data.RECEIVE_BLOCKING);
		} else {
			throw new NotSynchronousException(this);
		}
	}

	/**
	 * Returns a PDU received from SMSC. This receive will wait for
	 * maximum <code>timeout</code> time for a PDU; if there is
	 * no PDU received in the specified time, the function returns null.<br>
	 * Note that this method can be called only when bound as receiver
	 * or transciever.
	 *
	 * @return received pdu or null if none received
	 * 
	 * @exception IOException exception during communication
	 * @exception NotSynchronousException receive called in asynchronous mode
	 * @exception PDUException incorrect format of PDU
	 * @exception TimeoutException rest of data not received for too long time
	 * @exception UnknownCommandIdException PDU with unknown id was received
	 * @see Receiver
	 * @see ReceiverBase
	 */
	final public PDU receive(long timeout)
		throws UnknownCommandIdException, TimeoutException, NotSynchronousException, PDUException, IOException {
		PDU pdu = null;
		if (receiver.isReceiver()) {
			if (!asynchronous) {
				pdu = receiver.receive(timeout);
			} else {
				throw new NotSynchronousException(this);
			}
		} else {
			// throw?
		}
		return pdu;
	}

	/**
	 * Sends a response PDU. Use for sending responses for PDUs send
	 * from SMSC, e.g. DELIVERY_SM etc.
	 *
	 * @param response the response to be sent
	 * 
	 * @exception IOException exception during communication
	 * @exception ValueNotSetException optional param not set but requested
	 * @see Transmitter
	 */
	final public void respond(Response response) throws ValueNotSetException, IOException, WrongSessionStateException {
		checkState(response);
		debug.enter(DSESS, this, "respond(Response)");
		debug.write(DSESS, "Sending response " + response.debugString());
		try {
			transmitter.send(response);
		} catch (ValueNotSetException e) {
			event.write(e, "Sending a response.");
			debug.exit(DSESS, this);
			throw e;
		}
		debug.exit(DSESS, this);
	}

	/**
	 * Returns <code>Transmitter</code> object created for transmitting
	 * PDUs to SMSC.
	 *
	 * @return the <code>Transmitter</code> object
	 * @see Transmitter
	 */
	public Transmitter getTransmitter() {
		return transmitter;
	}

	/**
	 * Returns <code>Receiver</code> object created for receiving
	 * PDUs from SMSC.
	 *
	 * @return the <code>Receiver</code> object
	 * @see Receiver
	 */
	public Receiver getReceiver() {
		return receiver;
	}

	/**
	 * Returns <code>Connection</code> object provided for
	 * communication with SMSC.
	 *
	 * @return the <code>Connection</code> object
	 * @see Connection
	 */
	public Connection getConnection() {
		return connection;
	}

	/**
	 * The basic method for sending a <code>Request</code> PDU to SMSC
	 * and receiving correspondent <code>Response</code>, if applicable, and
	 * returns the received PDU.<br>
	 * In case there is a PDU received with unknown command id or with invalid
	 * length, <code>GenericNack</code> PDU is sent back to SMSC automatically
	 * to report the error and null is returned.
	 * If the timeout for receiving PDU set in the <code>Receiver</code>
	 * object expires, null is returned.
	 * <p>
	 * @param  request  the request PDU (not xxx_RESP) to be sent
	 * @return          the corresponding response or null in case of problems
	 *
	 * @exception IOException exception during communication
	 * @exception PDUException incorrect format of PDU
	 * @exception TimeoutException rest of data not received for too long time
	 * @exception ValueNotSetException optional param not set but requested
	 * @see Request
	 * @see Response
	 * @see GenericNack
	 * @see Transmitter
	 * @see Receiver
	 */
	final private Response send(Request request, boolean asynchronous)
		throws ValueNotSetException, TimeoutException, PDUException, IOException {
		debug.enter(DSESS, this, "send(Request)");
		Response response = null;
		debug.write(DSESS, "Sending request " + request.debugString());
		try {
			transmitter.send(request);
		} catch (ValueNotSetException e) {
			event.write(e, "Sending the request.");
			debug.exit(DSESS, this);
			throw e;
		}
		if ((!asynchronous) && (request.canResponse())) {
			PDU pdu = null;
			Response expResponse = null;
			expResponse = request.getResponse();
			try {
				debug.write(DSESS, "Going to receive response. Expecting " + expResponse.debugString());
				try {
					pdu = receiver.receive(expResponse);
				} catch (NotSynchronousException e) {
					debug.write("Unexpected NotSynchronousException caught, ignoring :-)");
				}
			} catch (UnknownCommandIdException e) {
				safeGenericNack(Data.ESME_RINVCMDID, e.getSequenceNumber());
			} catch (InvalidPDUException e) {
				if ((e.getException() instanceof NotEnoughDataInByteBufferException)
					|| (e.getException() instanceof TerminatingZeroNotFoundException)) {
					debug.write(DSESS, "wrong length " + e);
					debug.write(DSESS, " => sending gnack.");
					safeGenericNack(Data.ESME_RINVMSGLEN, e.getPDU().getSequenceNumber());
				} else {
					debug.write(DSESS, "InvalidPDUException - rethrowing " + e);
					debug.exit(DSESS, this);
					throw e;
				}
			} catch (TimeoutException e) {
				debug.write(DSESS, "TimeoutException - rethrowing " + e);
				debug.exit(DSESS, this);
				throw e;
			}
			if (pdu != null) {
				debug.write(DSESS, "Got response(?) pdu " + pdu.debugString());
				response = checkResponse(pdu, expResponse);
			} else {
				debug.write(DSESS, "No response received.");
			}
		}
		debug.exit(DSESS, this);
		return response;
	}

	/**
	 * Calls <code>send(Request,boolean)</code> with the current value of
	 * <code>asynchronous</code> flag.
	 * @see #send(Request,boolean)
	 */
	final private Response send(Request request)
		throws ValueNotSetException, TimeoutException, PDUException, IOException {
		return send(request, asynchronous);
	}

	/**
	 * Checks if the <code>pdu</code> received is
	 * matching the <code>expResponse</code> and returns corrected response.
	 * If the command id's don't match then if the <code>pdu</code>'s 
	 * command id is generic_nack, then the expected response is set
	 * the command id of generic_nack and command id, command status
	 * and sequence number of the received <code>pdu</code> and this
	 * way transformed response is returned: the class mathces, but
	 * the command id says, that the PDU is generic nack.<br>
	 * If the command id is not generic nack, then we received
	 * incorrect pdu as the sequence numbers match, so we send generic nack
	 * back to the smsc.
	 * if the command id's match, then the <code>pdu</code> is returned.
	 * @param pdu the received PDU which should be a response
	 * @param expResponse the response we expected from smsc
	 * @return either the received PDU or expected response transformed to
	 *         generic nack.
	 * @see #send(Request,boolean)
	 */
	private Response checkResponse(PDU pdu, Response expResponse)
		throws ValueNotSetException, TimeoutException, IOException {
		Response response = null;
		debug.write(DSESS, "checking response if it's what we expected.");
		if (pdu.getCommandId() != expResponse.getCommandId()) {
			debug.write(DSESS, "Got different response than expected " + expResponse.debugString());
			if (pdu.getCommandId() == Data.GENERIC_NACK) {
				// it's brutal, but it's necessary
				// we transform the response object to carry generic nack
				debug.write(DSESS, "Got generic nack. What could we do wrong?");
				expResponse.setCommandId(Data.GENERIC_NACK);
				expResponse.setCommandLength(pdu.getCommandLength());
				expResponse.setCommandStatus(pdu.getCommandStatus());
				expResponse.setSequenceNumber(pdu.getSequenceNumber());
				response = expResponse;
			} else {
				debug.write(DSESS, "invalid command id - sending gnack");
				safeGenericNack(Data.ESME_RINVCMDID, pdu.getSequenceNumber());
				response = null;
			}
		} else {
			// if the commandId is same as of the expected response's command id,
			// then the pdu must be Response as well
			response = (Response) pdu;
		}
		return response;
	}

	/**
	 * Sends a generic acknowledge with given comand status and sequence number
	 * and catches andy <code>SmppException</code>.
	 * @param commandStatus command status to report
	 * @param sequenceNumber to allow the other party to match the generic ack with
	 *                       their sent request
	 * @exception IOException if there is a comms error
	 */