Package org.dellroad.msrp

Class Session

java.lang.Object

org.dellroad.msrp.Session

public class Session
extends Object

Represents one MSRP session.

Method Summary

Modifier and Type	Method	Description
boolean	cancel(String messageId)	Cancel an outgoing message previously sent.
boolean	close(Exception cause)	Close this session.
MsrpUri	getLocalUri()	Get local URI.
MsrpUri	getRemoteUri()	Get remote URI.
String	send(byte[] content, String contentType, Iterable<? extends Header> headers, ReportListener reportListener)	Enqueue an outgoing message specified as a byte[] array.
String	send(InputStream input, int size, String contentType, Iterable<? extends Header> headers, ReportListener reportListener)	Enqueue an outgoing message specified as an InputStream.
String	send(Iterable<? extends Header> headers, ReportListener reportListener)	Enqueue an outgoing message with no content.
boolean	sendFailureReport(List<MsrpUri> toPath, String messageId, Status status)	Enqueue an outgoing failure report.
boolean	sendSuccessReport(List<MsrpUri> toPath, String messageId, ByteRange byteRange, Status status)	Enqueue an outgoing success report.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getLocalUri

public MsrpUri getLocalUri()

Get local URI.

Returns:

local URI

getRemoteUri

public MsrpUri getRemoteUri()

Get remote URI.

Returns:

remote URI

toString

public String toString()

Overrides:

toString in class Object

close

public boolean close(Exception cause)

Close this session.

Any FailureListeners associated with queued messages will be notified. This method is idempotent.

Parameters:

cause - error that occurred, if any, otherwise null

Returns:

true if this instance was closed, false if this instance was already closed

send

public String send(byte[] content,
                   String contentType,
                   Iterable<? extends Header> headers,
                   ReportListener reportListener)

Enqueue an outgoing message specified as a byte[] array.

Parameters:

content - message content

contentType - content type

headers - other headers (MIME and/or extension), or null for none

reportListener - success and/or failure listener, or null for none

Returns:

unique message ID, or null if this instance is closed

Throws:

IllegalArgumentException - if content or contentType is null

IllegalArgumentException - if headers contains an invalid header name or value

send

public String send(InputStream input,
                   int size,
                   String contentType,
                   Iterable<? extends Header> headers,
                   ReportListener reportListener)

Enqueue an outgoing message specified as an InputStream. This method will handle closing the provided input.

Parameters:

input - message content input; will be eventually closed by this method

size - size of input, or -1 if unknown; if positive and input is longer than this, it will be truncated

contentType - content type

headers - other headers (MIME and/or extension), or null for none

reportListener - success and/or failure listener, or null for none

Returns:

unique message ID, or null if this instance is closed

Throws:

IllegalArgumentException - if input or contentType is null

IllegalArgumentException - if size is less than -1

IllegalArgumentException - if headers contains an invalid header name or value

send

public String send(Iterable<? extends Header> headers,
                   ReportListener reportListener)

Enqueue an outgoing message with no content.

Parameters:

headers - other headers (MIME and/or extension), or null for none

reportListener - success and/or failure listener, or null for none

Returns:

unique message ID, or null if this instance is closed

Throws:

IllegalArgumentException - if input or contentType are not both null or both not-null

IllegalArgumentException - if size is less than -1 or input is null and size is not -1

IllegalArgumentException - if headers contains an invalid header name or value

cancel

public boolean cancel(String messageId)

Cancel an outgoing message previously sent.

Parameters:

messageId - message ID returned by send()

Returns:

true if message was canceled, false if message has already been completely sent

Throws:

IllegalArgumentException - if messageId is null

sendSuccessReport

public boolean sendSuccessReport(List<MsrpUri> toPath,
                                 String messageId,
                                 ByteRange byteRange,
                                 Status status)

Enqueue an outgoing success report.

Parameters:

toPath - path to the peer; should equal the From-Path from the received message

messageId - the Message-ID from the received message

status - success status, or null for default 200 Message Delivered

byteRange - byte range successfully received

Returns:

true if report was sent, false if report could not be sent because this instance is closed

Throws:

IllegalArgumentException - if toPath is null or empty

IllegalArgumentException - if messageId is null or invalid

IllegalArgumentException - if byteRange is null

sendFailureReport

public boolean sendFailureReport(List<MsrpUri> toPath,
                                 String messageId,
                                 Status status)

Enqueue an outgoing failure report.

Parameters:

toPath - path to the peer; should equal the From-Path from the received message

messageId - the Message-ID from the received message

status - failure status

Returns:

true if report was sent, false if report could not be sent because this instance is closed

Throws:

IllegalArgumentException - if toPath is null or empty

IllegalArgumentException - if messageId is null or invalid

IllegalArgumentException - if status is null