Thursday, April 28, 2011

SLEE Basic concepts, mini FAQ

     I have had this post in mind for quite some time now, some may find in trivial or redundant, however I feel it needed. FAQ on mobicents.org is not a good place for such content, JSR's dont have it(hidden in plain sight), since its simple specs, mobicents user guides may incorporate it in future. Soooo, as community member I decided to create some sort of little FAQ, since its always easier to understand something stated directly, than browse tons of pages, in search of concept one does not even comprehend or missunderstands.

      Each year there is some sort of of magic period, when lots of new users pop up in forums They ask. They really ask lots of questions. Thats a good thing, whats bad is that lots of questions are hard to understand, since new users mix/confuse SLEE concepts. Below you can find answers and clarification to some of them.

First lets explain some basic concepts:


1. SBB Abstract class(SBBA) 
       SBB Abstract class - is a class created by developer It contains all the service logic which SBB should perform. It implements javax.slee.Sbb interface. 

NOTE: SBBA MUST implement all methods from javax.slee.Sbb  interface, SLEE container does not provide those by default.
      SBB Abtract class must have following, concrete methods(implemented):
  • receive event handlers - for each definition of incoming event in descriptor, SBBA must have method on<>
  • methods defined in SBB LO (if any defined) - for each method defined there, SBBA must have concrete method with matchin signature
  • methods defined in javax.slee.Sbb
    Concrete methods define SBB Logic executed on call - be it an event, SBB LO call or SLEE callback.

     SBB Abstract class must have following, abstract methods:
  • fire event method, for each event defined as "Fireable" (check events direction), SBBA must have method fire<>
  • setter and getter for each CMP field defined in descriptor
  • method to fetch custom Activity Context Interface, if any is defined
  • methods to fetch usage parameter sets, if any defined
  • methods to fetch child relation object for each child relation defined, if any
   
    NOTE: As explained below, SBBA should not( or rather MUST NOT, but thats on devs responsibility) defined any class level variables to store any kind of state. It should use CMPs, ACI variables, profiles and some 3rd party resources, like database.

    Thats it, there is nothing more to that class.

2. SBB Concrete class(SBBC)

    SBB Concrete class is non abstract class. It is created by SLEE container upon deployment of SBB.         
    SLEE container implements all required methods(mandated by specs) present in SBBA. To put it simply, SBBC extends(in one way or another) SBB abstract class. 

   

3. SBB Entity (SBBE)

      SBBE is a logical entity(bad place for such word, but it is 100% accurate). It has no physical representation in what developer creates. It is maintained by SLEE container. 

     To put it simply, SBBE is a state of single SBB. More or less it consists of:
  • convergence name, ID
  • CMP fields of SBB (defined in SBBA)
  • activities to which SBB is attached
  • ACI variables
  • children references, if any children have been created
  • ....
     IMPORTANT: calls to SBBE state(like getter of CMP) outside of JSLEE calls WILL in most/all cases fail!


3. SBB LocalObject( SBBLO) 

  SBB Local object is an interface. Each SBB have it.  By default SLEE container provides implementation of javax.slee.SbbLocalObject interface. It allows limited management over SBBs (SBBE actaully).
Some may have non standard interface.  In such case user is responsible for implementation of methods defined in such, nonstandard interface, in SBB Abstract class.


4. SLEE Object Pools

       SLEE container creates pools of concrete objects( for profiles and SBBs ) from concrete classes(SBBC for instance. Pools are managed my container. Objects within those pools are assigned to serve a call. For instance, imagine following situation. Event is fired into SLEE, container in some way determines:
    - there is SBBE attached to activity 
    - it is capable of receiving said event
    - SBBE has no real object assigned

      SLEE container will do the following:
   - borrow SBBC object from pool
   - assign SBBC to SBBE  (now calls to SBBE state are valid, ie. getter of CMP can be called)
   - deliver said event to SBBC(actually handler is defined in SBBA) event handler
   - possibly terminate assgiment of SBBC to SBBE, in such case SBBC instance is returned to pool, SBBE state is stored somewhere in container.

5. SBB Concrete class(SBBC) vs SBB Abtract class (SBBA) vs SBB Entity 

    It is very common for new users to mix or confuse above. Diagram below may shed some light on this problem:




6. Root SBB vs child SBB

     Root SBB is a trigger point for service start. Each service defines root SBB. Root SBBE are create ONLY by SLEE container. They are created based on on logic defined below. Root SBBs can create children( children are created by code create by developer, NOT by SLEE container). Child SBBs can create more children.

   IMPORTANT: Only root SBBs are interrogated for initial events. Child SBBs are not. Thats a rule of thumb
  IMPORTANT: ONLY initial events are handled differently for Root SBBs, all other events are handled in the same way for Root and child SBBs


7. Initial Event Selector & convergence name

    Convergence name is a sort of hidden property of root SBB. Convergence name is unique in container.
    Initial event selectors allow to define custom convergence name. Variable selectors use SLEE variable(like EventTypeId) to compose convergence name.

   Initial Event Selector method is a callback method. It is called by SLEE container when descriptors points to it. Selector method is called to allow code to determine two things:
   - if event is AT all initial
   - compute convergence name(create, based on developer whim)

   Initial event selector method MUST be concrete method, implemented by developer  in SBBA. It takes single argument of type javax.slee.InitialEventSelector 

   IMPORTANT: if event in descriptor has initial-event set to false(attribute of event definition) selectors are ignored by SLEE container, ie, following event definition, wont create service instance when event is fired into SLEE:
<event event-direction="Receive" initial-event="False">
   <event-name>StartServiceEvent</event-name>
   <event-type-ref>
    <event-type-name>
     javax.slee.serviceactivity.ServiceStartedEvent
    </event-type-name>
    <event-type-vendor>javax.slee</event-type-vendor>
    <event-type-version>1.1</event-type-version>
   </event-type-ref>
   <initial-event-select variable="ActivityContext" />
  </event>
8. How SLEE creates instance of service/SBBE


    There are two ways to create SBBEs. First one required javax.slee.ChildRelation object. SBBE is created with call to create() method. It is done directly from SBBA code created by developer.

    Second one is managed by SLEE container. Simple flow looks as follows(not exactly, it is simplyfied):

   - create list(organized by priority) of ROOT SBBs defining EventType as initial.
   - determine if event is initial:
        * if variable is used: default true
        * if initial-event-selector-method is used, check its return value
   - compute convergence name( or fetch from InitialEventSelector )
   - check if there is SBBE for that convergence name exists, if not, create SBBE and attach to activity on which event is delivered
  - deliver event to SBBE

   Above procedure is repeated for all root SBBs in said list.

   IMPORTANT: Note that if SBBE exists, its not created, its only attached to activity on which event is delivered.


Guidelines: 
   1. Read specs, user guide and forums before posting. There is high chance one of said resources has answer to that question.
   2. If you post, give descriptive topic: "I have problem", "MGCP problem" or "Help I have problem/am in a hurry" is not descriptive, users, with similar problems wont be able to find it easly!
   3. Read exception/debug information - it may hold key to solve your problem.
   4. If you post please add as much info as possible. container name, container version, deployment config, conditions, traffic dump, etc....


Now some questions that I remember/googled from forums. If something is missing, send me email or add comment:

GENERAL Questions 

  1. I have SLEE 1.x, when SMPP5 RA will be  ported(or any new one)
     1.x reached its AOL loooong time ago, move to 2.x container or hack that resource. Core team does not have time to support everything :)
   
 2. How can I contribute?
   You have to sign contributors agreement, so code becomes open source: https://cla.jboss.org

 3. How can I create/send/receive XXX message?
   Read specific resources, check examples. Examples have sample code to create some basic interaction - ie. SIP messages, between two nodes. RFCs for SIP describe procedures used. If you still face problem, post with as much info as possible, step by step explanation what you do, core member or community member may have time to shed some light there.

  4. Which container is better SS or SLEE?
    There is no such thing as better container. Those are created in two different technologies. Performance wise they are quite similar. However there are key differences.
   SLEE:
   - RA abstraction allows easy integration of any type of protocol or resource(even hardware)
   -  transactional by default
   - requires more time to comprehend
   - requires some low level knowledge about protocols used
   - similar to EJB in some way
   - well defined container facilities


   SS:
   - based on well known Servlets programming model
   - out of box integration between HTTP and SIP(SIP & HTTP oriented only)
   - not transactional by default, JTA requires user hacks
   -  well defined help utilities - like Proxy or B2BUAHelper
  
   Depending on application purpose,available time, previous experience of dev team, one of them is more suitable. Detailed list of differences can be found here.

GENERAL SLEE Questions


 1. When SBBE is removed?
    SBBE are removed in one of two cases:
        - explicit removal from developer code
        - SBBE attachment count - number of activities to which SBBE is attached, reaches zero.



    If none of above happens, SBBE lingers in memory and performs actions developer coded it to perform. 

  2. Can I store profile data in some other place than default JPA resource?
      Yes. Check profiles lifecycle methods. By default containers handles callbacks and actions associated with them. However you can provide implementation, which will be respected by container.

  


ERROR Reports
  
 1. DU deployment gives error: xxxxx violates SLEE specification section x.y.z, what should I do?
      Read that section, validators in container print that information for a reason. If error says component violates some section, it does.


 2. Container start/DU deployment throws exception with weird content:
 - method not found
 - wrong arguments
 - etc...

    Clean container, if you get your hands dirty, you have to wash them, same thing applies to container. Remove everything you deployed previously before playing with source. Better, fetch clean AS and play in it.
  If problem persists it means that source is outdated. Now to solve that perform following:
    - update every source you use and rebuild
    - possibly update .m2/settings.xml and add nexus:
<repositories>
        <repository>
          <id>jboss-public-repository-group</id>
          <name>JBoss Public Maven Repository Group</name>
          <url>https://repository.jboss.org/nexus/content/groups/public/</url>
          <layout>default</layout>
          <releases>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
          </releases>
          <snapshots>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
          </snapshots>
        </repository>
      </repositories>

      <pluginRepositories>
        <pluginRepository>
          <id>jboss-public-repository-group</id>
          <name>JBoss Public Maven Repository Group</name>
          <url>https://repository.jboss.org/nexus/content/groups/public/</url>
          <layout>default</layout>
          <releases>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
          </releases>
          <snapshots>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
          </snapshots>
        </pluginRepository>
      </pluginRepositories>

}
  3. Deployment shows error similar to: Missing dependencies for mobicents-
slee-example-sip11-b2b-DU-2.4.0.CR1.jar:
    ....
    ....
    Well there is no other way! Deploy dependencies to make this nasty error go away. You can always check status of deployment via SLEE Twiddle or directly via AS JMX-Console.