SIP Annotations

SIP Servlet 1.1 defines four annotations that may be used in SIP applications. Using these annotations simplifies SIP application development by making the sip.xml deployment descriptor optional. See The sip.xml Deployment Descriptor.

Table 1–2 SIP Annotations

Annotation	Description
@SipServlet	Marks the class as a SIP servlet.
@SipListener	Marks the class as an implementation class of one of the SIP listeners.
@SipApplication	An application-level class to define a collection of SIP servlets.
@SipApplicationKey	Associates an incoming request and SIP session with a particular SipApplicationSession.

Using the @SipServlet Annotation

The javax.servlet.sip.annotation.SipServlet class-level annotation is used to mark the class as a SIP servlet.

---

Example 1–1 Example of the @SipServlet Annotation

@SipServlet
public class MyServlet extends SipServlet {
	...
}

---

@SipServlet has the following elements:

Table 1–3 @SipServlet Elements

Element	Description
applicationName	Explicitly associates the SIP servlet with a particular SIP application. This element is optional.
description	An optional description of this SIP servlet.
loadOnStartup	An int value representing the order this SIP servlet should be loaded on application deployment. The default value is -1, meaning the SIP servlet will not load until the container receives a request that the servlet handles. The lower the non-negative integer value in loadOnStartup, the earlier the SIP servlet will be initialized.
name	An optional name for this SIP servlet.

Using the @SipListener Annotation

The javax.servlet.sip.annotation.SipListener class-level annotation is used to mark the class as an implementation class of one of the SIP event listener interfaces. See SIP Listeners for information on SIP listeners.

Table 1–4 @SipListener Elements

Element	Description
applicationName	Explicitly associates the SIP listener with a particular SIP application. This element is optional.
name	An optional name for this SIP listener.

Using the @SipApplication Annotation

The javax.servlet.sip.annotation.SipApplication application-level annotation is used to define a collection of SIP servlets and SIP listeners with a common configuration. @SipApplication is annotated at the package level, and all SIP servlets or listeners within the package are part of the defined SIP application unless the SIP servlet or listener explicitly sets the applicationName element in the @SipServlet or @SipListener annotation, respectively.

@SipApplication should be annotated either in a package-info.java file in a package hierarchy, or before the package definition in a particular source file.

---

Example 1–2 Example of @SipApplication Annotation in a package-info.java File

@SipApplication(name="MySipApplication")
package com.example.sip;

---

Table 1–5 @SipApplication Elements

Element	Description
name	The name of the logical collection of SIP servlets and listeners. This element is required.
description	Optional description of the SIP application.
displayName	Optional name for displaying in container administration tools. Defaults to the value of the name element.
distributable	Optional boolean indicating whether the application may be distributed by the container in a clustered environment. The default value is false.
largeIcon	An optional String indicating the location, relative to the root path of the archive, of a large icon for representing this application in container administration tools.
mainServlet	The optional name of the main SIP servlet for this application.
proxyTimeout	An optional int value indicating the number of whole seconds before a timeout for all proxy operations in this SIP application.
sessionTimeout	An optional int value indicating the number of whole minutes before an application session timeout for all application sessions in this SIP application.
smallIcon	An optional String indicating the location, relative to the root path of the archive, of a small icon for representing this application in container administration tools.

Using the @SipApplicationKey Annotation

The javax.servlet.sip.annotation.SipApplicatonKey method-level annotation associates an incoming request with a particular SIpApplicationSession instance.

The method annotated by @SipApplicationKey must:

• Be public.

• Be static.

• Return a String.

• Define a single argument of type SipServletRequest.

• Not modify the passed-in SipServletRequest object.

The returned String is the key used to associate the request with a SipApplicationSession instance.

---

Example 1–3 Example of @SipApplicationKey

@SipApplication
package com.example.sip;
...
public class MySipApplication {
	@SipApplicationKey
	public static String sessionKey (SipServletRequest req) {
		return hash(req.getRequestURI() + getDomain(req.getFrom());
	}
}
	

---

Only one @SipApplicationKey method should be defined for a particular SIP application.

Table 1–6 @SipApplicationKey Elements

Element	Description
applicationName	Explicitly associates the SIP application key with a particular SIP application. This element is optional.