001: /**
002: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
003: * Unpublished - rights reserved under the Copyright Laws of the United States.
004: * Copyright © 2003 Sun Microsystems, Inc. All rights reserved.
005: * Copyright © 2005 BEA Systems, Inc. All rights reserved.
006: *
007: * Use is subject to license terms.
008: *
009: * This distribution may include materials developed by third parties.
010: *
011: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
012: *
013: * Module Name : JSIP Specification
014: * File Name : MessageFactory.java
015: * Author : Phelim O'Doherty
016: *
017: * HISTORY
018: * Version Date Author Comments
019: * 1.1 08/10/2002 Phelim O'Doherty Initial version
020: * 1.2 11/15/2004 M. Ranganathan Null argument for createSipRequest creates am empty Sip Request
021: * Added new method to create a response from a String
022: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
023: */package javax.sip.message;
024:
025: import java.text.ParseException;
026: import javax.sip.header.*;
027: import javax.sip.address.URI;
028: import java.util.List;
029:
030: /**
031: * This interface provides factory methods that allow an application to create
032: * Request and Response messages from a particular implementation of JAIN SIP.
033: * This class is a singleton and can be retrieved from the
034: * {@link javax.sip.SipFactory#createMessageFactory()}.
035: *
036: * @author BEA Systems, NIST
037: * @version 1.2
038: */
039: public interface MessageFactory {
040:
041: // Standard Request Creation methods
042:
043: /**
044: * Creates a new Request message of type specified by the method paramater,
045: * containing the URI of the Request, the mandatory headers of the message
046: * with a body in the form of a Java object and the body content type.
047: *
048: * @param requestURI the new URI object of the requestURI value of this Message.
049: * @param method the new string of the method value of this Message.
050: * @param callId the new CallIdHeader object of the callId value of this Message.
051: * @param cSeq the new CSeqHeader object of the cSeq value of this Message.
052: * @param from the new FromHeader object of the from value of this Message.
053: * @param to the new ToHeader object of the to value of this Message.
054: * @param via the new List object of the ViaHeaders of this Message.
055: * @param contentType the new ContentTypeHeader object of the content type
056: * value of this Message.
057: * @param content the new Object of the body content value of this Message.
058: * @return the newly created Request object.
059: * @throws ParseException which signals that an error has been reached
060: * unexpectedly while parsing the method or the body.
061: */
062: public Request createRequest(URI requestURI, String method,
063: CallIdHeader callId, CSeqHeader cSeq, FromHeader from,
064: ToHeader to, List via, MaxForwardsHeader maxForwards,
065: ContentTypeHeader contentType, Object content)
066: throws ParseException;
067:
068: /**
069: * Creates a new Request message of type specified by the method paramater,
070: * containing the URI of the Request, the mandatory headers of the message
071: * with a body in the form of a byte array and body content type.
072: *
073: * @param requestURI the new URI object of the requestURI value of this Message.
074: * @param method the new string of the method value of this Message.
075: * @param callId the new CallIdHeader object of the callId value of this Message.
076: * @param cSeq the new CSeqHeader object of the cSeq value of this Message.
077: * @param from the new FromHeader object of the from value of this Message.
078: * @param to the new ToHeader object of the to value of this Message.
079: * @param via the new List object of the ViaHeaders of this Message.
080: * @param contentType the new ContentTypeHeader object of the content type
081: * value of this Message.
082: * @param content the new byte array of the body content value of this Message.
083: * @return the newly created Request object.
084: * @throws ParseException which signals that an error has been reached
085: * unexpectedly while parsing the method or the body.
086: */
087: public Request createRequest(URI requestURI, String method,
088: CallIdHeader callId, CSeqHeader cSeq, FromHeader from,
089: ToHeader to, List via, MaxForwardsHeader maxForwards,
090: ContentTypeHeader contentType, byte[] content)
091: throws ParseException;
092:
093: /**
094: * Creates a new Request message of type specified by the method paramater,
095: * containing the URI of the Request, the mandatory headers of the message.
096: * This new Request does not contain a body.
097: *
098: * @param requestURI the new URI object of the requestURI value of this Message.
099: * @param method the new string of the method value of this Message.
100: * @param callId the new CallIdHeader object of the callId value of this Message.
101: * @param cSeq the new CSeqHeader object of the cSeq value of this Message.
102: * @param from the new FromHeader object of the from value of this Message.
103: * @param to the new ToHeader object of the to value of this Message.
104: * @param via the new List object of the ViaHeaders of this Message.
105: * @return the newly created Request object.
106: * @throws ParseException which signals that an error has been reached
107: * unexpectedly while parsing the method.
108: */
109: public Request createRequest(URI requestURI, String method,
110: CallIdHeader callId, CSeqHeader cSeq, FromHeader from,
111: ToHeader to, List via, MaxForwardsHeader maxForwards)
112: throws ParseException;
113:
114: // generic create message method
115:
116: /**
117: * Create a new SIP Request object based on a specific string value. This
118: * method parses the supplied string into a SIP Request. The request
119: * string should only consist of the SIP portion of the Request and not
120: * the content. Supplying a null argument creates an empty SIP Request
121: * which may be used to end out "keep alive" messages for a connection.
122: *
123: * @param request the new string value of the Request.
124: * @return the newly created Request object.
125: * @throws ParseException which signals that an error has been reached
126: * unexpectedly while parsing the request.
127: */
128: public Request createRequest(String request) throws ParseException;
129:
130: // Standard Response Creation methods
131:
132: /**
133: * Creates a new Response message of type specified by the statusCode
134: * paramater, containing the mandatory headers of the message with a body
135: * in the form of a Java object and the body content type.
136: *
137: * @param statusCode the new integer of the statusCode value of this Message.
138: * @param callId the new CallIdHeader object of the callId value of this Message.
139: * @param cSeq the new CSeqHeader object of the cSeq value of this Message.
140: * @param from the new FromHeader object of the from value of this Message.
141: * @param to the new ToHeader object of the to value of this Message.
142: * @param via the new List object of the ViaHeaders of this Message.
143: * @param contentType the new ContentTypeHeader object of the content type
144: * value of this Message.
145: * @param content the new Object of the body content value of this Message.
146: * @return the newly created Response object.
147: * @throws ParseException which signals that an error has been reached
148: * unexpectedly while parsing the statusCode or the body.
149: */
150: public Response createResponse(int statusCode, CallIdHeader callId,
151: CSeqHeader cSeq, FromHeader from, ToHeader to, List via,
152: MaxForwardsHeader maxForwards,
153: ContentTypeHeader contentType, Object content)
154: throws ParseException;
155:
156: /**
157: * Creates a new Response message of type specified by the statusCode
158: * paramater, containing the mandatory headers of the message with a body
159: * in the form of a byte array and the body content type.
160: *
161: * @param statusCode the new integer of the statusCode value of this Message.
162: * @param callId the new CallIdHeader object of the callId value of this Message.
163: * @param cSeq the new CSeqHeader object of the cSeq value of this Message.
164: * @param from the new FromHeader object of the from value of this Message.
165: * @param to the new ToHeader object of the to value of this Message.
166: * @param via the new List object of the ViaHeaders of this Message.
167: * @param contentType the new ContentTypeHeader object of the content type
168: * value of this Message.
169: * @param content the new byte array of the body content value of this Message.
170: * @return the newly created Response object.
171: * @throws ParseException which signals that an error has been reached
172: * unexpectedly while parsing the statusCode or the body.
173: */
174: public Response createResponse(int statusCode, CallIdHeader callId,
175: CSeqHeader cSeq, FromHeader from, ToHeader to, List via,
176: MaxForwardsHeader maxForwards,
177: ContentTypeHeader contentType, byte[] content)
178: throws ParseException;
179:
180: /**
181: * Creates a new Response message of type specified by the statusCode
182: * paramater, containing the mandatory headers of the message. This new
183: * Response does not contain a body.
184: *
185: * @param statusCode the new integer of the statusCode value of this Message.
186: * @param callId the new CallIdHeader object of the callId value of this Message.
187: * @param cSeq the new CSeqHeader object of the cSeq value of this Message.
188: * @param from the new FromHeader object of the from value of this Message.
189: * @param to the new ToHeader object of the to value of this Message.
190: * @param via the new List object of the ViaHeaders of this Message.
191: * @return the newly created Response object.
192: * @throws ParseException which signals that an error has been reached
193: * unexpectedly while parsing the statusCode.
194: */
195: public Response createResponse(int statusCode, CallIdHeader callId,
196: CSeqHeader cSeq, FromHeader from, ToHeader to, List via,
197: MaxForwardsHeader maxForwards) throws ParseException;
198:
199: // Response Creation methods based on a Request
200:
201: /**
202: * Creates a new Response message of type specified by the statusCode
203: * paramater, based on a specific Request with a new body in the form of a
204: * Java object and the body content type. Only the required headers are
205: * copied from the Request.
206: *
207: * @param statusCode the new integer of the statusCode value of this Message.
208: * @param request the received Reqest object upon which to base the Response.
209: * @param contentType the new ContentTypeHeader object of the content type
210: * value of this Message.
211: * @param content the new Object of the body content value of this Message.
212: * @return the newly created Response object.
213: * @throws ParseException which signals that an error has been reached
214: * unexpectedly while parsing the statusCode or the body.
215: */
216: public Response createResponse(int statusCode, Request request,
217: ContentTypeHeader contentType, Object content)
218: throws ParseException;
219:
220: /**
221: * Creates a new Response message of type specified by the statusCode
222: * paramater, based on a specific Request with a new body in the form of a
223: * byte array and the body content type. Only the required headers are
224: * copied from the Request.
225: *
226: * @param statusCode the new integer of the statusCode value of this Message.
227: * @param request the received Reqest object upon which to base the Response.
228: * @param contentType the new ContentTypeHeader object of the content type
229: * value of this Message.
230: * @param content the new byte array of the body content value of this Message.
231: * @return the newly created Response object.
232: * @throws ParseException which signals that an error has been reached
233: * unexpectedly while parsing the statusCode or the body.
234: */
235: public Response createResponse(int statusCode, Request request,
236: ContentTypeHeader contentType, byte[] content)
237: throws ParseException;
238:
239: /**
240: * Creates a new Response message of type specified by the statusCode
241: * paramater, based on a specific Request message. This new Response does
242: * not contain a body. Only the required headers are copied from the
243: * Request.
244: *
245: * @param statusCode the new integer of the statusCode value of this Message.
246: * @param request the received Reqest object upon which to base the Response.
247: * @return the newly created Response object.
248: * @throws ParseException which signals that an error has been reached
249: * unexpectedly while parsing the statusCode.
250: */
251: public Response createResponse(int statusCode, Request request)
252: throws ParseException;
253:
254: /**
255: * Creates a Response from a String. This method parses the supplied string
256: * into a SIP Response. The response string should only consist of the
257: * SIP portion of the Response and not the content.
258: *
259: * @param response is a string representing the response. The argument should
260: * only contain the Sip Headers and not the body of the response.
261: * @throws ParseException which signals an error has been reached unexpectedly
262: * while parsing the response.
263: * @since v1.2
264: *
265: */
266: public Response createResponse(String response)
267: throws ParseException;
268:
269: }
|