Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "JAIN_SLEE_Example_User_Guide.ent">
%BOOK_ENTITIES;
]>

<section id="location_sbb">
	<title>LocationSbb</title>
	<para>
		<literal>LocationSbb</literal> is responsible
		for storing and managing expiration of address bindings.
	</para>
	<para>
		Class
		<literal>org.mobicents.slee.services.sip.location.LocationSbb
		</literal>
		includes all the service logic required to perform management of contact addresses.
	</para>

	<section id="location_sbb_interface">
		<title>SBB Interface</title>
		<para>
			<literal>LocationSbb</literal>
			declares custom
			<literal>SbbLocalObject</literal>
			interface. Declared methods are used by
			<literal>ProxySbb</literal>
			and
			<literal>RegistrarSbb</literal>
			to access registration data. Declaration in sbb-jar.xml look as follows:
		</para>
		<programlisting language="XML" role="XML"><![CDATA[
 <sbb-jar>
	<sbb id="sip-registrar-location-sbb">
		
		<description>Location Service - JPA based</description>
		
		<sbb-name>LocationSbb</sbb-name>
		<sbb-vendor>org.mobicents</sbb-vendor>
		<sbb-version>1.2</sbb-version>

		<library-ref>
        	<library-name>sip-services-library</library-name>
        	<library-vendor>org.mobicents</library-vendor>
        	<library-version>1.2</library-version>
    	</library-ref>

		<sbb-classes>
			<sbb-abstract-class>
				<sbb-abstract-class-name>
					org.mobicents.slee.services.sip.location.LocationSbb
				</sbb-abstract-class-name>

			</sbb-abstract-class>
			<sbb-local-interface>
				<sbb-local-interface-name>
					org.mobicents.slee.services.sip.location.LocationSbbLocalObject
				</sbb-local-interface-name>
			</sbb-local-interface>
			...
		</sbb-classes>
			
			... 
	</sbb>
</sbb-jar>
		]]>
		</programlisting>
		 
		<para><literal>org.mobicents.slee.services.sip.location.LocationSbbLocalObject</literal> is defined as follows: </para>
		<programlisting language="Java" role="JAVA">
		package org.mobicents.slee.services.sip.location;

		import javax.slee.SbbLocalObject;

		public interface LocationSbbLocalObject extends SbbLocalObject,LocationService {
			
		}
		
		
		
		package org.mobicents.slee.services.sip.location;

		public interface LocationService extends ... {
		
			/**
			 * Adds new contact binding for particular user..
			 * 
			 * @param sipAddress -
			 *            sip address of record sip:ala@ma.kota.w.domu.com
			 * @param contactAddress -
			 *            contact address - tel:+381243256
			 * @param comment -
			 *            possible comment note
			 * @param expires -
			 *            long - seconds for which this contact is to remain valid
			 * @param registrationDate -
			 *            long - date when the registration was created/updated
			 * @param qValue -
			 *            q parameter
			 * @param callId -
			 *            call id
			 * @param cSeq -
			 *            seq numbers
			 * @return - binding created in this operation
			 * @throws LocationServiceException
			 */
			public RegistrationBinding addBinding(String sipAddress,
					String contactAddress, String comment, long expires,
					long registrationDate, float qValue, String callId, long cSeq)
					throws LocationServiceException;
		
			/**
			 * Returns set of user that have registered - set contains adress of record
			 * for each user, something like sip:ala@kocia.domena.com
			 * 
			 * @return
			 * @throws LocationServiceException 
			 */
			public Set&lt;String&gt; getRegisteredUsers() throws LocationServiceException;
		
			/**
			 * Returns map which contains mapping contactAddress->registrationBinding
			 * for particular user - address of record sip:nie@ma.mnie.tu
			 * 
			 * @param sipAddress
			 * @return
			 * @throws LocationServiceException
			 */
			public Map&lt;String, RegistrationBinding&gt; getBindings(String sipAddress)
					throws LocationServiceException;
		
		
			/**
			 * Updates the specified registration binding.
			 * 
			 * @param registrationBinding	
			 * @throws LocationServiceException
			 */
			public void updateBinding(RegistrationBinding registrationBinding)
					throws LocationServiceException;
		
			/**
			 * Removes contact address from user bindings.
			 * 
			 * @param sip address of record -
			 *            sip:ala@kocia.domena.au
			 * @param contactAddress -
			 *            tel:+481234567890
			 * @throws LocationServiceException
			 */
			public void removeBinding(String sipAddress, String contactAddress)
					throws LocationServiceException;
		
		
			...
			
		}
		</programlisting>
		<para>Methods defined by <literal>LocationSbbLocalObject</literal> are implemented by <literal>LocationSbb</literal> class.
		Those methods are invoked in synchronous manner in order to perform binding operations:</para>
		<itemizedlist>
			<listitem>
				<para>add binding and create expiration timer</para>
				 <programlisting language="Java" role="JAVA">
public RegistrationBinding addBinding(String sipAddress,
	String contactAddress, String comment, long expires, long registrationDate,
	float qValue, String callId, long cSeq)
	throws LocationServiceException {
			
					// add binding
	RegistrationBinding registrationBinding = locationService.addBinding(
		sipAddress, contactAddress, comment, expires, registrationDate
		, qValue, callId, cSeq);
	if (logger.isDebugEnabled()) {
		logger.debug("addBinding: "+registrationBinding);
	}
	// create null aci
	NullActivity nullActivity = nullActivityFactory.createNullActivity();
	ActivityContextInterface aci = null;
	try {
		aci = nullACIFactory.getActivityContextInterface(nullActivity);
		// set name
		activityContextNamingFacility.bind(aci, getACIName(contactAddress, sipAddress));
	} catch (Exception e) {
		throw new LocationServiceException(e.getLocalizedMessage());
	}
	// atach to this activity
	aci.attach(sbbContext.getSbbLocalObject());
	// set timer
	TimerID timerID = timerFacility.setTimer(aci, null,registrationDate + 
		((expires+1)*1000), defaultTimerOptions);
	// save data in aci 
	RegistrationBindingActivityContextInterface rgAci = asSbbActivityContextInterface(aci);
	rgAci.setTimerID(timerID);
	rgAci.setContactAddress(contactAddress);
	rgAci.setSipAddress(sipAddress);
			
	if(logger.isInfoEnabled()) {
		logger.info("added binding: sipAddress="+sipAddress+"
			,contactAddress="+contactAddress);
	}
			
	return registrationBinding;
}
				 </programlisting>
			</listitem> 
			<listitem>
				<para>update binding and restart expiration timer</para> 
				<programlisting language="Java" role="JAVA">
public void updateBinding(RegistrationBinding registrationBinding)
	throws LocationServiceException {
				
	if (logger.isDebugEnabled()) {
		logger.debug("updateBinding: registrationBinding="+registrationBinding);
	}
				
	// get named aci
	ActivityContextInterface aci = activityContextNamingFacility.lookup(
		getACIName(registrationBinding.getContactAddress()
		, registrationBinding.getSipAddress()));
	// get the timer id from the aci and reset the timer
	RegistrationBindingActivityContextInterface rgAci = asSbbActivityContextInterface(aci);
	timerFacility.cancelTimer(rgAci.getTimerID());
	rgAci.setTimerID(timerFacility.setTimer(aci, null
		, registrationBinding.getRegistrationDate() 
		+ ((registrationBinding.getExpires()+1) * 1000), defaultTimerOptions));
	// update in location service
	locationService.updateBinding(registrationBinding);
				
	if(logger.isInfoEnabled()) {
		logger.info("binding updated: sipAddress="+registrationBinding.getSipAddress()
		+",contactAddress="+registrationBinding.getContactAddress());
	}
}
				</programlisting>
			</listitem> 
			<listitem>
				<para>remove binding and cancel expiration timer</para> 
				<programlisting language="Java" role="JAVA">
public void removeBinding(String sipAddress, String contactAddress)
	throws LocationServiceException {
		
	if (logger.isDebugEnabled()) {
		logger.debug("removeBinding: sipAddress="+sipAddress+"
			,contactAddress="+contactAddress);
	}
						
	try {
		// lookup null aci from aci naming facility, get timerid and cancel
		// timer (when present).
		ActivityContextInterface aci = activityContextNamingFacility
			.lookup(getACIName(contactAddress, sipAddress));
		if (aci != null) {
			timerFacility.cancelTimer(asSbbActivityContextInterface(aci)
								.getTimerID());
			activityContextNamingFacility.unbind(getACIName(contactAddress, sipAddress));
			// end null activity, detach is no good because this is a different
			// sbb entity then the one that create the binding
			((NullActivity)aci.getActivity()).endActivity();
		}
	} catch (Exception e) {
		throw new LocationServiceException(e.getLocalizedMessage());
	}
	// remove from location service		
	locationService.removeBinding(sipAddress, contactAddress);
				
	if(logger.isInfoEnabled()) {
		logger.info("removed binding: sipAddress="+sipAddress+"
			,contactAddress="+contactAddress);
	}
}
				</programlisting>
			</listitem> 
			<listitem>
				<para>get registered users <acronym>AOR</acronym> </para>
				 <programlisting language="Java" role="JAVA">
	public Set&lt;String&gt; getRegisteredUsers() throws LocationServiceException {
		
		if (logger.isDebugEnabled()) {
			logger.debug("getRegisteredUsers");
		}
		
		return locationService.getRegisteredUsers();
	}
				 </programlisting>
			</listitem> 
			<listitem>
				<para>retrieve all bindings for <literal>AOR</literal> </para> 
				<programlisting language="Java" role="JAVA">
	public Map&lt;String, RegistrationBinding&gt; getBindings(String sipAddress)
			throws LocationServiceException {
		
		if (logger.isDebugEnabled()) {
			logger.debug("getBindings: sipAddress="+sipAddress);
		}
		
		return locationService.getBindings(sipAddress);
	}
				 </programlisting>
			</listitem> 
		</itemizedlist>
	</section>
	<section id="location_sbb_aci">
		<title>SBB Activity Context Interface</title>
		<para><literal>LocationSbb</literal> defines custom <literal>Activity Context Interface</literal> with variables.
		Variables are used to store data required to manage expiration timer and access binding in storage, that is: </para>
		<itemizedlist>
			<listitem>
				<para><acronym>JSLEE</acronym> timer id of timer running for contact address</para>
			</listitem>
			<listitem>
				<para>contact address for which expiration timer runs</para>
			</listitem>
			<listitem>
				<para>sip address (<acronym>AOR</acronym>) of binding</para>
			</listitem>
		</itemizedlist>
		<para>Custom <literal>Activity Context Interface</literal> is defined in sbb-jar.xml descriptor as follows:</para>
		<programlisting language="XML" role="XML"><![CDATA[
<sbb id="sip-registrar-location-sbb">
		
		<description>Location Service - JPA based</description>
		
		<sbb-name>LocationSbb</sbb-name>
		<sbb-vendor>org.mobicents</sbb-vendor>
		<sbb-version>1.2</sbb-version>

		<library-ref>
        	<library-name>sip-services-library</library-name>
        	<library-vendor>org.mobicents</library-vendor>
        	<library-version>1.2</library-version>
    	</library-ref>

		<sbb-classes>
			<sbb-abstract-class>
				<sbb-abstract-class-name>
					org.mobicents.slee.services.sip.location.LocationSbb
				</sbb-abstract-class-name>

			</sbb-abstract-class>
			...
			<sbb-activity-context-interface>
				<sbb-activity-context-interface-name>
					org.mobicents.slee.services.sip.location.RegistrationBindingActivityContextInterface
				</sbb-activity-context-interface-name>
			</sbb-activity-context-interface>
		</sbb-classes>
		...
	</sbb>
</sbb-jar>
		]]>
		</programlisting>
		<para>Custom <literal>Activity Context Interface</literal> accessor is defined as follows:</para>
		<programlisting language="Java" role="JAVA">
public abstract class LocationSbb implements ... {
	public abstract RegistrationBindingActivityContextInterface asSbbActivityContextInterface(
			ActivityContextInterface aci);
}
		</programlisting>
		<para>Variables are defined in <literal>Java Bean</literal> convetion, by declaration of setter and getter pair in custom <literal>Activity Context Interface</literal>:</para>
		<programlisting language="Java" role="JAVA">
public interface RegistrationBindingActivityContextInterface extends ActivityContextInterface {

	public abstract TimerID getTimerID();
	public abstract void setTimerID(TimerID timerID);
	
	public abstract String getContactAddress();
	public abstract void setContactAddress(String contactAddress);
	
	public abstract String getSipAddress();
	public abstract void setSipAddress(String sipAddress);
	
}
		</programlisting>
	</section>
	<section id="location_sbb_timer">
		<title>Expiration timer</title>
		<para>Timer supervising expiration is created with binding. Its attached to named <acronym>ACI</acronym>. Timeout value is based on data passed from <literal>RegistrarSbb.</literal> </para>
		<para>Timer event handler is invoked in case of contact address expiration, its purpose is to:</para>
		<itemizedlist>
			<listitem>
				<para>retrieve data stored in custom  <literal>Activity Context Interface</literal></para>
			</listitem>
			<listitem>
				<para>clean <acronym>ACI</acronym> name binding</para>
			</listitem>
			<listitem>
				<para>remove <acronym>AOR</acronym> binding from <literal>LocationService</literal> </para>
			</listitem>
		</itemizedlist>
		<para>Timer event handler is defined as follows: </para>
		<programlisting language="Java" role="JAVA">
	public void onTimerEvent(TimerEvent timer, ActivityContextInterface aci) {

		if (logger.isFineEnabled()) {
			logger.fine("onTimerEvent()");
		}
		
		aci.detach(sbbContext.getSbbLocalObject());
			
		// cast to rg aci
		RegistrationBindingActivityContextInterface rgAci = asSbbActivityContextInterface(aci);
		// get data from aci
		String contactAddress = rgAci.getContactAddress();
		String sipAddress = rgAci.getSipAddress();
		
		// unbind from aci so it ends
		try {
			activityContextNamingFacility.unbind(getACIName(contactAddress, sipAddress));
		} catch (Exception e) {
			logger.severe("",e);
		}
		// remove rg from location service	
		try {
			locationService.removeBinding(sipAddress, contactAddress);
		} catch (Exception e) {
			logger.severe("",e);
		}

		if(logger.isInfoEnabled()) {
			logger.info("binding expired: sipAddress="+sipAddress+"
				,contactAddress="+contactAddress);
		}
		
	}
		</programlisting>
	</section>
	<section id="location_sbb_aci_naming">
		<title>SBB Activity Context Interface naming</title>
		<para><literal>LocationSbb</literal> associates name to <acronym>ACI</acronym> on which expiration timer runs. This makes <acronym>ACI</acronym> accessible with given name.
		Name and <acronym>ACI</acronym> association is created with <acronym>JSLEE</acronym> <literal>Activity Context Naming Facility</literal>.
		Name uniquely identifies <literal>Timer</literal> <acronym>ACI</acronym> for given <acronym>AOR</acronym> and contact address.</para>
	</section>
	<section id="location_sbb_aci_env">
		<title>SBB environment entries</title>
		<para><literal>LocationSbb</literal> environment entry controls <literal>LocationService</literal> type used(JPA and local). 
		<acronym>XML</acronym> descriptor defines entry as follows:  </para>
		<programlisting language="XML" role="XML"><![CDATA[
<sbb id="sip-registrar-location-sbb">
		
		<description>Location Service - JPA based</description>
		
		<sbb-name>LocationSbb</sbb-name>
		<sbb-vendor>org.mobicents</sbb-vendor>
		<sbb-version>1.2</sbb-version>

		<library-ref>
        	<library-name>sip-services-library</library-name>
        	<library-vendor>org.mobicents</library-vendor>
        	<library-version>1.2</library-version>
    	</library-ref>

		...
		<env-entry>
			<env-entry-name>LOCATION_SERVICE_CLASS_NAME</env-entry-name>
			<env-entry-type>java.lang.String</env-entry-type>
			<!-- choose your location service, filtered on compliation -->
			<env-entry-value>
				org.mobicents.slee.services.sip.location.nonha.NonHALocationService
			</env-entry-value>
		</env-entry>
	</sbb>
</sbb-jar>
		]]>
		</programlisting>
		<para>Environment entries are accessible with <acronym>JNDI</acronym> lookups:</para>
		<programlisting language="Java" role="JAVA">
		
		Context myEnv = (Context) new InitialContext().lookup("java:comp/env");	
		String value  = (String) myEnv.lookup("LOCATION_SERVICE_CLASS_NAME");
		
		</programlisting>
	</section>

</section>	
New to GrepCode? Check out our FAQ X