
OPENNESS API SAMPLES
====================


How to start:

- the sample code is proposed in the form of a Maven project
- if you do not use Maven, all the necessary libraries are in the /lib directory.
- compile the code
- then you can launch each sample of the /sample/application directory.

What is needed to run a sample:

- 2 users created on the Open Touch server. For the devices, use 3PCC compliant sets. My IC 8082 Phones (with at least
  R300 version) are recommended.
- the client-rest.properties file updated with the host or ip address of the Open Touch server
- one <login>.properties file created with the data of each user, <login> is the login of the user in Open Touch server
- Open Touch server licenses ICE_TELAPI_BASIC and ICE_TELAPI_ADVANCED are necessary to run the samples
- Update the sample and launch it


Samples
=======

The samples are the entry points, there are 6, independent and can be run separately.

Sample1MakeCall : User1 (Alice) calls User2 (Bob), User2 does not answer, User1 hangs up.
---------------
This sample does not use subscription.
 - Get data for both users
 - Get authentication and open a session for User1
 - User1 calls User2 which rings but does not answer
 - After short pause, User1 releases the call
 - Close session of User1

Sample2Subscription : User1 (Alice) calls User2 (Bob), User2 does not answer, User1 hangs up.
-------------------
This sample uses subscription to get the call ref and to release only the call associated to this call ref.
 - Get data for both users
 - Get authentication and open a session for User1
 - User1 subscribes to the telephony events
 - User1 calls User2 which rings but does not answer
 - User1 gets the call reference
 - After short pause, User1 releases the call
 - User1 closes the subscription
 - Close session of User1

Sample3AnsweredCall : User1 (Alice) calls User2 (Bob), User2 answers and hangs up after a wait timer.
-------------------
This sample uses subscription to get the call ref and to answer and release the call.
 - Get data and authentication of both users
 - Open a session for both users
 - User2 subscribes to the telephony events
 - User1 calls User2 which rings
 - User2 gets the call reference and use it to answer the incoming call
 - After short pause, User2 releases the call
 - User2 closes the subscription
 - Close session for both users

Sample4SessionHandling : A session is opened and maintained open during 24 hours for one user
----------------------
 - Once opened, a session has a limited time life period. The duration is retrieved at session opening.
 - Only one user is used for this sample, it authenticates and opens a session.
 - The session time to live duration is get at the opening and used in a periodic activated thread. Then each time the
   thread is activated, it refreshes the session. Note that this scenario will stop itself only after 24 hours.

Sample5SubscriptionKeepAlive : Based on Sample4SessionKeepAlive and add subscription event handling with keep alive.
----------------------------
As the Session, the Subscription is also subject to a keep alive mechanism, but slightly different : once subscribed
the server will close the subscription after a timer even if events are still received. The client has to reopen it
after its closure, for this it has 1 minute during them the server will retain the events so that none are lost.
 - Only one user is used for this sample, it authenticates and opens a session which is maintained to life by a periodic
   activated thread.
 - Then a subscription is done to all telephonic events. The default time to live from the subscription is 10 minutes,
   during these, the events are simply logged.
 - When the server closes the subscription, the client connects again and cycle begins again ...
 - The scenario stops itself only after 24 hours.

Sample6CommunicationLog : Caller calls Callee which does not answer. Caller hangs up, Callee receives "missed call" through subscription
-----------------------
This sample shows a subscription to (and reception from) a communication log event. It re-uses mechanisms from previous
samples like make call and event subscription.
 - Both users authenticate themselves and open a session
 - Caller subscribes to telephonic events and Callee to communication log events
 - Caller calls Callee which rings but does not answer
 - Caller gets the call reference and closes its event subscription
 - After short pause, Caller releases the call
 - The call without answer will be notified to Callee through its communication log subscription
 - Once the "missed call" received, Callee closes its subscription
 - To finish both users close they sessions


Architecture
============

The project is divided into 5 packages:
- sample.application : contains the samples.
- sample.config : contains the configuration aspects, read of system and users configuration.
- sample.core : contains the business aspects, for instance description of sequence between the client and Open Touch for authentication.
- sample.rest : contains the sample.rest resources management, the description of the exchanged data.
- sample.transport :contains the management of the http transport, use of jersey.
The 3 last ones (sample.core sample.rest sample.transport) are ordered as top-down layers, and the sample.application lays on top of them.

This "in layers" architecture has been chosen in order to be to most easy to understand, the aim of the project is only
to explain how to use the Open Touch API. It gives only a few examples which the developer can rely on to understand
the API philosophy. This is one of many implementation structure API use.


Details
=======

For authentication, only basic authentication is proposed.


Traces
======

To activate traces on client side, update the log4j.xml file.
To have logs in a file, update api.log.file property in the file client-rest.properties


To activate traces on server side, update (or ask your installer to update)
the file /opt/Alcatel-Lucent/infra_services/chameleon/webapps/api/WEB-INF/web.xml

in the servlet <servlet-name>API OPENNESS V1</servlet-name>
set the param com.sun.jersey.sample.config.feature.Trace to true
<init-param>
	<param-name>com.sun.jersey.sample.config.feature.Trace</param-name>
	<param-value>true</param-value>
</init-param>