JAIN SLEE 1.0 Specification, Final Release

Transcription

1 JAIN SLEE 1.0 Specificatin, Final Release Specificatin Leads: Swee Bn Lim Sun Micrsystems, Inc. David Ferry Open Clud Limited

2 JAIN SLEE 1.0 Specificatin, Final Release 1/30/ :00:00 Cpyright Sun Micrsystems, Inc. 901 San Antni Ave, Pal Alt, CA 94303, USA. Cpyright Open Clud Limited Level 12, Sun Micrsystems Huse, 70 The Terrace, Wellingtn, New Zealand All rights reserved

3 Table f Cntents Table f Cntents Chapter 1 Intrductin Target audience Typgraphic and terminlgy cnventins Acknwledgements Organizatin Gals Scpe Relatinship with JAIN TM... 4 Chapter 2 Overview Scpe f the SLEE specificatin Cmpnent mdel Prvisined data SLEE Facilities Resurces and resurce adaptrs Event ruting Management interfaces Packaging Main abstractins SBB cmpnent SBB graph and rt SBB SBB entities SBB entity trees and rt SBB entities Event delivery pririty Cascading remval f SBB entity sub-tree SBB bject SBB lcal interface and SBB lcal bject Activity Activity bject Activity Cntext Hw the SLEE reclaims an SBB entity tree Activity Cntext reclamatin and SBB entity tree remval example Activity Cntext Interface interface and bject Prfile, Prfile Table, and Prfile Specificatin Service Service state Deplyable unit Management interface Rles...17 JAIN SLEE 1.0 Specificatin, Final Release Page iii

4 Table f Cntents SBB Develper Service Deplyer Administratr...17 Chapter 3 Putting it Tgether Create an SBB cmpnent Cmpnent identity f an SBB cmpnent Building an SBB frm child SBBs SBB lcal interface SBB abstract class SBB Activity Cntext Interface interface SBB Usage Parameters interface Recmmended SBB interfaces and classes naming cnventin SBB deplyment descriptr SBB jar file SBB jar file example Custm event types Event type deplyment descriptr Event type packaging Event jar file Event jar file example Prfile Specificatin Prfile CMP interface Prfile Management interface Prfile Management abstract class Prfile Specificatin deplyment descriptr Recmmended Prfile interfaces and classes naming cnventin Prfile Specificatin jar file Prfile Specificatin jar file example Create a Service Service deplyment descriptr Cmpnent identity f a Service Custmizing the Service t the peratinal envirnment Packaging the Service fr deplyment Deplying cmpnents Deplyable unit jar file example Administer Services and Prfiles...36 Chapter 4 Addresses Address bjects AddressPlan bjects Address string...40 JAIN SLEE 1.0 Specificatin, Final Release Page iv

5 Table f Cntents 4.4 AddressPresentatin bjects AddressScreening bjects Address example...42 Chapter 5 SBB Lcal Interface Hw t btain an SBB lcal bject What can be dne with an SBB lcal bject A typical scenari Pass-by-reference semantics The SbbLcalObject interface SbbLcalObject interface isidentical methd SbbLcalObject interface setsbbpririty methd SbbLcalObject interface getsbbpririty methd SbbLcalObject interface remve methd The SBB lcal interface...46 Chapter 6 The SBB Abstract Class Overview Cncrete methds Abstract methds SBB bject life cycle SBB abstract class life cycle methds setsbbcntext methd unsetsbbcntext methd sbbcreate methd sbbpstcreate methd sbbactivate methd sbbpassivate methd sbbremve methd sbblad methd sbbstre methd SbbCntext interface SbbCntext interface getsbblcalobject methd SbbCntext interface getservice methd SbbCntext interface getsbb methd Cntainer Managed Persistence (CMP) CMP field accessr methd rules CMP field example Nn-persistent state SBB abstract class get Prfile CMP methds SBB abstract class get child relatin methds...60 JAIN SLEE 1.0 Specificatin, Final Release Page v

6 Table f Cntents ChildRelatin interface ChildRelatin interface create methd ChildRelatin interface Cllectin methds Transactinal semantics SBB abstract class exceptin callback methd RuntimeExceptin handling fr transactinal methds RuntimeExceptin handling fr nn-transactinal methds SBB abstract class sbbexceptinthrwn methd SBB abstract class exceptin callback methds example SBB abstract class and SbbCntext interface transactin methds SBB abstract class sbbrlledback callback methd SbbCntext interface setrllbackonly methd SbbCntext interface getrllbackonly methd SBB abstract class and SbbCntext interface transactin methds example Nn-reentrant and re-entrant SBB cmpnents Methd name restrictins SBB cmpnent envirnment SBB cmpnent envirnment as a JNDI naming cntext Resurce adaptr type defined Activity Cntext Interface Factry bject references Resurce adaptr bject references EJB references The SLEE s respnsibility Operatins allwed in the methds f the SBB abstract class SBB abstract class methds invked by the SBB abstract class...76 Chapter 7 Activity Objects, Activity Cntexts, and Activity Cntext Interface Objects Relatins Activity bjects and Activity Cntexts Activity Cntexts and Activity Cntext Interface bjects Activity Cntexts and SBB entities Activity Cntexts and SLEE Facilities Activity bject Surces f Activity bjects Getting an Activity bject Firing events n an Activity bject Firing events n an Activity Cntext Every Activity bject has an end Activity End Event Activity Cntext Activity Cntext creatin...83 JAIN SLEE 1.0 Specificatin, Final Release Page vi

7 Table f Cntents Activity Cntext peratins Activity Cntext state machine Activity and Activity Cntext end examples Generic ActivityCntextInterface interface ActivityCntextInterface interface getactivity methd ActivityCntextInterface interface attach methd ActivityCntextInterface interface detach methd ActivityCntextInterface interface isending methd SBB Activity Cntext Interface interface SBB Activity Cntext Interface get and set accessr methds Getting an Activity Cntext Interface bject Activity Cntext Interface Factry bjects Activity Cntext methds in SBB abstract class and SbbCntext SbbCntext interface getactivities methd SBB abstract class assbbactivitycntextinterface methd Activity Cntext attribute aliasing Activity Cntext attribute aliasing deplyment descriptr elements Activity Cntext attribute aliasing example Activity Cntext Naming Facility Activity Cntext Naming Facility and Activity End Events NullActivity bjects NullActivity interface NullActivityFactry interface NullActivityCntextInterfaceFactry interface All NullActivity methds are transactinal Ending a NullActivity bject JNDI names f NullActivity related bjects Activity Cntext and Activity bject persistence...98 Chapter 8 Events Overview Event prducers Event cnsumers SBB as an event prducer and fire event methds SBB as an event cnsumer and event handler methds Event bject Event class Event type Custm event types Nn-custm event types Event name JAIN SLEE 1.0 Specificatin, Final Release Page vii

8 Table f Cntents 8.2 Events and Activity Cntexts Firing an event n an Activity Cntext and a default address Receiving an event n an Activity Cntext Event related deplyment descriptr elements Event prducer deplyment descriptr elements Event related SBB deplyment descriptr elements Feature interactin analysis SBB abstract class and SbbCntext interface event methds SBB abstract class fire event methds SBB abstract class event handler methds SbbCntext interface maskevent and geteventmask methds Event ruting Initial events Cmputing the cnvergence name Selecting cnvergence name variables Initial event selectr methd SBB entities Cncurrency cntrl Event delivery p ririty Event delivery semantics Autmatic event subscriptin Initial event subscriptin Received event subscriptin Service Started Event and ServiceActivity bjects ServiceActivity bjects Ending a ServiceActivity bject Service Started Events ServiceActivityFactry interface ServiceActivityCntextInterfaceFactry interface JNDI names f ServiceActivity related bjects Chapter 9 Transactins Benefits Atmicity Islatin N demarcatin API Transactin state machine Active state Cmmitting state Cmmitted state Marked fr Rllback state Rlling Back state JAIN SLEE 1.0 Specificatin, Final Release Page viii

9 Table f Cntents Rlled Back state Transactinal methds Mandatry transactinal methds Required transactinal methds Nn-transactinal methds Unspecified transactin cntext SLEE and nn-slee riginated methd invcatins Special cnsideratins fr cascading remval peratins SLEE riginated invcatin SLEE riginated invcatins and transactins Examples f valid SLEE riginated invcatin sequences An illustrated example f a transactin Transactinal resurces and EJB invcatins FIFO rdering f asynchrnusly fired events Nn-transactinal resurces Transactins exceptin handling and rlled back handling Nn-SLEE riginated methd invcatin SLEE riginated methd invcatin SLEE riginated transactin exceptin and rlled back handling example Transactin rlled back callback handling Chapter 10 Prfiles and Prfile Specificatins Intrductin Relatinships Prfile Table names, Prfile names, and Prfile identifiers Prfile Table and Prfile addresses Default Prfile f a Prfile Table PrfileID class Prfile Table Events and PrfileTableActivity bjects PrfileTableActivity bjects Prfile Added Events Prfile Updated Events Prfile Remved Events PrfileTableActivityCntextInterfaceFactry interface Prfile Specificatin Views f a Prfile Specificatin SBB Develper s SBB bject view SBB Develper s management view Administratr s view Prfile CMP interface Prfile references in Prfile CMP interface Prfile Management interface JAIN SLEE 1.0 Specificatin, Final Release Page ix

10 Table f Cntents 10.8 Prfile Management abstract class Prfile Management bjects Transient state PrfileManagement interface prfileinitialize callback methd prfilelad callback methd prfilestre callback methd prfileverify callback methd isprfiledirty and markprfiledirty methds isprfilevalid methd Hiding and renaming Prfile CMP interface accessr methds Uses A Prfile Specificatin example Java type usage Prfile Tables referenced by a Service Resurce Inf Prfile Table Address Prfile Table Deplyment prcessing Prfile MBean Requirements fr the Prfile MBean interface Requirements fr the Prfile MBean class PrfileMBean interface Life cycles Life cycle f a Prfile Life cycle f Prfile MBean bjects Prfile MBean bject management Prfile editing Management client islatin SBB bject view updates Chapter 11 Usage Parameters Usage parameter types SBB Usage Parameters interface Cunter-type usage parameter increment methd Sample-type usage parameter methd SBB Usage Parameters interface deplyment descriptr SBB Usage Parameters interface example SBB usage parameter sets Default SBB usage parameter set Named SBB usage parameter set Getting access t an SBB usage parameter set Get SBB Usage Parameter methd JAIN SLEE 1.0 Specificatin, Final Release Page x

11 Table f Cntents Get SBB Usage Parameter methd example Chapter 12 Runtime Envirnment APIs prvided by SLEE Java 2 APIs SLEE 1.0 APIs JNDI Prgramming restrictins Chapter 13 Facilities Timer Facility TimerID interface TimerFacility interface TimerOptins bjects Delays in delivering Timer Events Timer Events Desired Timer Facility behavir and Timer Facility pseud cde Alarm Facility AlarmFacility interface Implementatin recmmendatin Level bjects Trace Facility TraceFacility interface Implementatin recmmendatin Activity Cntext Naming Facility ActivityCntextNamingFacility interface Cnference bridge example Prfile Facility PrfileFacility interface Frmat f the alarm type and message type string JNDI names f SLEE Facilities Chapter 14 Management Mtivatin fr JMX instrumentatin SLEE MBean interfaces and classes Implementatin requirements fr a SLEE MBean class Requirements fr the management client Accessing the MBean Server and SLEE MBean bjects Requirements f the Management Client Requirements f the SLEE Vendr Accessing SLEE MBean bjects SleePrviderFactry class JAIN SLEE 1.0 Specificatin, Final Release Page xi

12 Table f Cntents getsleeprvider methds Vendr implemented SleePrvider cncrete class SleeManagementMBean interface Operatinal states f the SLEE SleeManagementMBean interface SleeState bjects SleeStateChangeNtificatin class DeplymentMBean interface Cmpnents that can be installed Pre-cnditins fr installing and uninstalling a jar file Deplyable unit identifiers and descriptrs Cmpnent identity Cmpnent identifiers Cmmn characteristics f cmpnent identifier interfaces Cmpnent descriptrs DeplymentMBean interface ServiceManagementMBean interface ServiceState bjects ServiceUsageMBean interface SBB Usage MBean Requirements fr the SBB Usage MBean interface Requirements fr the usage parameter accessr methd Requirements fr the SBB Usage MBean class SbbUsageMBean interface UsageNtificatin class UsageUpdatedFilter class UsageOutOfRangeFilter class UsageThreshldFilter class PrfilePrvisiningMBean interface Cllectin bjects Alarm Facility management interface AlarmMBean interface AlarmNtificatin class AlarmLevelFilter class AlarmDuplicateFilter class AlarmThreshldFilter class Trace Facility management interface TraceMBean interface TraceNtificatin class TraceLevelFilter class JAIN SLEE 1.0 Specificatin, Final Release Page xii

13 Table f Cntents Security Chapter 15 Resurce Adaptrs Resurce adaptr type Resurce adaptr type identifiers Resurce adaptr type deplyment descriptr Resurce adaptr type packaging Resurce adaptr type jar file Resurce adaptr type jar file example Resurce adaptr Resurce adaptr deplyment descriptr Resurce adaptr packaging Resurce adaptr jar file Resurce adaptr jar file example Accessing Activity Cntext Interface Factries frm within an SBB Accessing resurce bjects frm within an SBB Accessing multiple resurce adaptr entities Example cde Event delivery semantics n newly created Activity bjects Transactin cntext prpagatin Resurce adaptr entity firing an event Resurce event filters Resurce adaptr entity and Activity Cntext interactins Appendix A Event Ruter Frmal Mdel A.1 Ntatin A.2 Definitins A.2.1 Events A.2.2 Child relatins A.2.3 SBB Cmpnents A.2.4 Child relatin bjects A.2.5 SBB Entities A.2.6 Services A.2.7 Activity Cntexts A.3 Further Prperties A.3.1 Uniqueness f SBB Entities A.3.2 Cnvergence names A.3.3 Delivered and attached A.3.4 Descendents and ancestrs A.3.5 Pririty f attached SBB entities with respect t an Activity Cntext and event A.3.6 Attachment cunt A.3.7 Cnsistency f child-parent relatins JAIN SLEE 1.0 Specificatin, Final Release Page xiii

14 Table f Cntents A.3.8 A.3.9 Uniqueness f SBB entities with respect t child relatin bjects Inclusin f child SBB entities in child relatin bjects A.3.10 Rt SBB entities A.3.11 Reachability f existing SBB entities frm a rt SBB entity A.4 Event queue A.5 Event ruting A.5.1 A.5.2 Attach an SBB entity (sbbe) t an Activity Cntext (ac) Detach an SBB entity (sbbe) frm an Activity Cntext (ac) A.5.3 Mask the events ( names EventNames ) fr an SBB entity (sbbe) n n Activity Cntext (ac) A.5.4 A.5.5 A.5.6 Remve an SBB entity (sbbe) frm a parent SBB entity (p) Create a rt SBB entity (sbbe) based n a child relatin bject (cr) belnging t a Service Create a nn-rt SBB entity (sbbe) based n a child relatin bject (cr) belnging t an SBB entity (p) A.5.7 Receipt f event (e) n an Activity Cntext (ac) A.5.8 Delivery f event (e) n an Activity Cntext (ac) A.5.9 Terminatin f an Activity Cntext (ac) A.5.10 On cmpletin f event ruting fr an event (e) Appendix B Event Ruter Pseud Cde B.1 Definitins B.2 ActivityCntextInterface interface attach methd pseud cde B.3 ActivityCntextInterface interface detach methd pseud cde B.4 SbbCntext interface getactivities methd pseud cde B.5 SbbCntext interface geteventmask methd pseud cde B.6 SbbCntext interface maskevent methd pseud cde B.7 SbbLcalObject interface getsbbpririty methd pseud cde B.8 SbbLcalObject interface setsbbpririty methd pseud cde B.9 SbbLcalObject interface remve methd pseud cde B.10 ChildRelatin interface create methd pseud cde B.11 SBB abstract class fire event methd pseud cde B.12 Event ruter pseud cde Appendix C JCC Resurce Adaptr Type C.1 Resurce adaptr type identifier C.2 Activity bjects C.3 Events C.3.1 Event types C.3.2 Event classes C.4 Activity Cntext Interface Factry interface C.5 Resurce adaptr bject JAIN SLEE 1.0 Specificatin, Final Release Page xiv

15 Table f Cntents C.6 Restrictins Appendix D JAIN SIP Resurce Adaptr Type D.1 Resurce Adaptr type identifier D.2 Activity bjects D.3 Events D.3.1 Event types D.3.2 Event classes D.4 Activity Cntext Interface Factry interface D.5 Resurce adaptr bject D.6 Restrictins Appendix E JAIN TCAP Resurce Adaptr Type E.1 Resurce adaptr type identifier E.2 Activity bjects E.3 Events E.3.1 Event types E.3.2 Event classes E.4 Activity Cntext Interface Factry interface E.5 Resurce adaptr bject E.6 Restrictins Appendix F Integratin with EJB applicatins F.1 Invking an EJB F.1.1 Example cde F.2 Passing an event t SLEE F.2.1 Example cde Appendix G Frequently Asked Questins G.1 Persistence G.2 SLEE event mdel versus JavaBeans listener mdel G.3 SLEE riginated invcatin vs. nn-slee riginated invcatin design G.4 Writing a sbbrlledback methd Glssary JAIN SLEE 1.0 Specificatin, Final Release Page xv

16 Chapter 1 Intrductin Chapter 1 Intrductin This is the specificatin f the JAIN TM Service Lgic and Executin Envirnment (SLEE) architecture. This architecture defines a cmpnent mdel fr structuring the applicatin lgic f cmmunicatins applicatins as a cllectin f reusable bject-riented cmpnents, and fr cmpsing these cmpnents int mre sphisticated services. The SLEE architecture als defines the cntract between these cmpnents and the cntainer that will hst these cmp nents at runtime. The SLEE specificatin supprts the develpment f highly available and scaleable distributed SLEE specificatin cmpliant applicatin servers, but des nt mandate any particular impleme ntatin strategy. Mre imprtantly, applicatins may be written nce, and then deplyed n any applicatin server that cmplies with the SLEE specificatin. In additin t the applicatin cmpnent mdel, the SLEE specificatin als defines the management interfaces used t administer the applicatin server and the applicatin cmpnents executing within the applicatin server. It als defines a set f standard Facilities, like the Timer Facility, Trace Facility, and Alarm Facility. 1.1 Target audience The target audiences fr this specificatin are cmmunicatin applicatin develpers, vendrs f the cmmunicatin applicatin servers, and telecmmunicatins prduct vendrs in the areas f Sftswitches, SIP Prxy servers, Call Agents, and traditinal class 4 r 5 switches wh wish t deply services n their prduct which are develped by service creatrs fllwing the JAIN SLEE specificatin. 1.2 Typgraphic and terminlgy cnventins The SLEE specificatin uses the fllwing typgraphic cnventins: Lgical Entity. Wrds with the first character capitalized describe a lgical r cnceptual entity defined by the SLEE specificatin, e.g. Activity, Activity Cntext, SBB, Service, Prfile, and Prfile Table. InterfaceOrClass. A single wrd in a fixed width fnt and made up f cncatenated wrds, with the first character f each wrd capitalized, identifies a Java class r interface, e.g. the TimerID interface, the CallBlckingSbb abstract class and the FService abstract class. deplyment-descriptr-element. A single wrd in a fixed width fnt and made up f lwercase wrd(s) jined by a h yphen identifies a deplyment descriptr element, e.g. sbb, sbb-classes, sbb-abstractclass-name. The SLEE specificatin uses the fllwing terminlgy cnventins: <entity> entity refers t an instance f a lgical r cnceptual entity, e.g. an SBB entity. <entity> bject refers t a Java bject that represents an entity and prvides the entity with a Java bject that can be invked t manipulate the entity, e.g. Activity bject. <class> bject refers t a Java bject and this Java bject is an instance f the specified class, e.g. a CallBlckingSbb bject, a FService bject. <interface> bject refers t a Java bject and this Java bject implements the specified interface, e.g. a TimerID bject. 1.3 Acknwledgements The JAIN SLEE architecture is a brad effrt that includes cntributins frm numerus peple at Sun, Open Clud, and at partner cmpanies. JAIN SLEE 1.0 Specificatin, Final Release Page 1

17 Chapter 1 Intrductin We acknwledge Phelim O Dherty f Sun, David Page, Steven Adams, Kryn Grant, Oliver Jwett, Ben Evans, Matthew Huttn, Catherine Allen and Nick Earle f Open Clud fr their valuable direct cntributins. They wrte and edited many chapters and appendices in this dcument and prvided much needed critical reviews. We thank the members f the JAIN SLEE Expert Grup fr their cntributins t this specificatin. The expert grup members include: Chammika Subasinghe f Fujitsu, Gal Shachr, Shmuel Kallner, Je McIntyre f IBM, Anders Lundqvist and Mickael Larssn f Incmit, Herb Ca lhun f Mtrla, Jhn Strrie f Nrtel Netwrks, Atsuyshi Shirat, Shinji Tanaka and Hideki Shina f NTT, Yarn Sheffer and Teddy Pard f Persneta, Ulf Lange f Siemens, and Ramana Devarapalli and Stuart Brad f TrueTel Cmmunicatins, Michael Maretzke f Vdafne. We thank Subdh Bapat, Charlie Tierney, Rb Gedman, and Margaret Nilsn f Sun, and David Lng f Open Clud fr their enthusiastic supprt and cntinuing t dedicate valuable resurces t this effrt thrughut its lng gestatin prcess. We thank Duglas Tait, Steven Grver, and Gary Bruce f the JAIN team fr their tireless effrt in prmting JAIN, and mre specifically, the JAIN SLEE. We als thank Vlada Matena and Mark Hapner f the Sun Micrsystems J2EE team fr sharing their expertise in cmp nent mdels and applicatin server architectures. 1.4 Organizatin This dcument is divided up int several chapters as fllws: Chapter 2, Overview discusses at a high level each f the cncepts required in rder t understand the JAIN SLEE architecture. Chapter 3, Putting it Tgether discusses hw a develper wuld implement a Service Building Blck (SBB) cmpnent, cmpse SBB cmpnents int higher level SBB cmpnents and Service cmpnents, define cmpnents fr custm event types and prvisined data, deply and administer Service cmpnents. Chapter 4, Addresses discusses addresses. Chapter 5, SBB Lcal Interface discusses hw an SBB cmpnent defines its lcal interface that is used by ther SBBs t invke this SBB in a synchrnus manner. Chapter 6, The SBB Abstract Class discusses the SBB abstract class and the life cycle f its instances. Chapter 7, Activity Objects, Activity Cntexts, and Activity Cntext Interface Objects discusses Activities and Activity bjects, hw Activities are represented in the SLEE by Activity Cntexts, the Activity Cntext Interface bjects that expse the attributes f an Activity Cntext and the relatinships f these bjects t ther bjects and entities. Chapter 8, Events discusses the SLEE event architecture, defining events, and the semantics f firing and receiving events. Chapter 9, Transactins discusses hw the SLEE uses well-established transactin cncepts t respnd t unexpected failures during executin. Chapter 10, Prfiles and Prfile Specificatins discusses defining the schema and behavir f Prfiles using Prfile Specificatins, the classes and interfaces that implement these Prfile Specificatins, and the life cycle f instances f these classes. Chapter 11, Usage Parameters discusses defining cunters and sample sets that are updated by SBB cmpnents and the peratins available t manage usage parameter sets and the data cntained within them. Chapter 12, Runtime Envirnment discusses the applicatin prgramming interfaces prvided by the SLEE at runtime and the restrictins that the SLEE impses n cmpnents running in the SLEE. JAIN SLEE 1.0 Specificatin, Final Release Page 2

18 Chapter 1 Intrductin Chapter 13, Facilities discusses the standard Facilities defined by the SLEE specificatin. Chapter 14, Management discusses the management interfaces expsed by the SLEE inclu ding thse fr subscriptin management, Service management, and management f the SLEE Facilities. Chapter 15, Resurce Adaptrs discusses resurces, resurce types, and hw resurces interact with the SLEE. Appendix A, Event Ruter Frmal Mdel discusses the desired behavir f the SLEE event ruter with a frmal mathematical specificatin. Appendix B, Event Ruter Pseud Cde discusses the desired behavir f the SLEE event ruter using pseud cde. Appendix C, JCC Resurce Adaptr Type discusses the recmmended way t adapt and plug JCC resurces int the SLEE. Appendix D, JAIN SIP Resurce Adaptr Type discusses the recmmended way t adapt and plug JAIN SIP resurces int the SLEE. Appendix E, JAIN TCAP Resurce Adaptr Type discusses the re cmmended way t adapt and plug JAIN TCAP resurces int the SLEE. Appendix F, Integratin with EJB applicatins discusses the recmmended way t integrate JAIN SLEE with Enterprise JavaBeans 1.5 Gals The JAIN Service Lgic and Executin Envirnment (SLEE) architecture has the fllwing gals: Define the standard cmpnent architecture fr building distributed bject-riented cmmunicatins applicatins in the Java prgramming language. Allw the develpment f distributable cmmunicatin applicatins by cmbining cmpnents develped using tls frm different vendrs. Supprt simple applicatin develpment. Applicatin develpers wi ll nt have t understand lwlevel transactin and state management details, multi-threading, cnnectin pling, and ther cmplex lw-level APIs. Adpt the Write Once, Run Anywhere philsphy f the Java prgramming language. Applicatin cmpnents can be develped nce, and then deplyed n multiple platfrms withut recmpilatin r surce cde mdificatin. Address the develpment, deplyment, and runtime aspects f a cmmunicatins applicatin s life cycle. Define the interfaces that enable cmmunicatin applicatins frm multiple vendrs t develp and deply cmpnents that can interperate at runtime. Cmpatible with the Enterprise JavaBeans (EJB) specificatin and the Java Naming and Directry Interface (JNDI) specificatin. SLEE vendrs shuld be able build an implementatin f the SLEE specificatin n an EJB 2.0 cmpliant J2EE implementatin. J2EE vendrs may als chse t extend their existing EJB servers t supprt JAIN SLEE applicatins. Cmpatible with the Java Management Extensins (JMX) specificatin. JMX can be used as an instrument that can be cntrlled by a JMX server. Cmpatible with ther Java prgramming language APIs. 1.6 Scpe The first versin f the JAIN SLEE specificatin deals with cmmnly used functins that are rutinely required in an executin platfrm, where applicatin develpers need t prvide the applicatin lgic. This JAIN SLEE 1.0 Specificatin, Final Release Page 3

19 Chapter 1 Intrductin typical functinality deals with the applicatin life cycle installatin, management and executin - and the framewrk under which the applicatins run. This specificatin des nt address the cnnectin f external resurces, such as prtcl stacks, t the SLEE. This interface will be addressed in a subsequent revisin. 1.7 Relatinship with JAIN TM The JAIN TM APIs fr Integrated Netwrks bring service prtability, cnvergence, and secure netwrk access t telephny and data netwrks. By prviding a new level f abstractin and assciated Java interfaces fr service creatin acrss Public Switched Telephne Netwrk (PSTN), packet (e.g. Internet Prtcl (IP) r Asynchrnus Transfer Mde (ATM)) and wireless netwrks, JAIN technlgy enables the integratin f Internet and Intelligent Netwrk (IN) prtcls. This is referred t as Integrated Netwrks. Furthermre, by allwing Java applicatins t have secure access t resurces inside the netwrk, the pprtunity is created t deliver thusands f services rather than the dzens currently available. Thus, JAIN technlgy is changing the cmmunicatins market frm many prprietary clsed systems t a single netwrk architecture where services can be rapidly created and deplyed. The JAIN Service Lgic Executin Envirnment (SLEE) is an integral part f the set f JAIN API s. It functin is f cre imprtance, it is the lgic and executin envirnment in which cmmunicatin applicatins are deplyed t utilize the varius netwrk resurces defined by the ther JAIN API s. In essence, the JAIN SLEE specificatin defines interfaces and requirements fr cmmunicatin applicatins within a carrier grade cmmunicatins platfrm utilizing ther JAIN and nn-jain cmmunicatin standards. JAIN SLEE 1.0 Specificatin, Final Release Page 4

20 Chapter 2 Overview Chapter 2 Overview A SLEE is an applicatin server. This applicatin server is a cntainer fr sftware cmp nents. The SLEE specificatin is designed and ptimized fr event driven applicatins. The SLEE specificatin is targeted at users f a SLEE. These users include the develper f sftware cmpnents running n the SLEE and Administratrs managing the sftware cmp nents deplyed n the SLEE. This specificatin des nt specify hw a SLEE vendr shuld implement a SLEE and the underlying technlgy. Multiple implementatin chices allw multiple SLEE vendrs t differentiate their prducts and t ensure diversity in the SLEE market. 2.1 Scpe f the SLEE specificatin The SLEE specificatin specifies: The SLEE cmpnent mdel and hw it supprts event driven applicatins as SLEE cmpnents. Hw SLEE cmpnents can be cmpsed and invke each ther. Hw prvisined data is specified, externally managed and accessed by SLEE cmpnents. SLEE Facilities. Hw resurces fit int the SLEE architecture and hw SLEE applicatins interact with these resurces. Hw events are ruted t applicatin cmpnents. The management interfaces f a SLEE. Hw applicatins are packaged fr deplyment int a SLEE Cmpnent mdel The SLEE cmpnent mdel is targeted at event driven applicatins, als knwn as asynchrnus applicatins. These applicatins receive requests in the frm f events Events and event types An event represents an ccurrence that requires applicatin prcessing. It carries infrmatin that describes the ccurrence, such as the surce f the event. An event may riginate frm: An external resurce such as a cmmunicatins prtcl stack. Within the SLEE. The SLEE uses events t cmmunicate changes in the SLEE that may be f interest t applicatins running in the SLEE. Fr example, the Timer Facility emits an event when a timer has expired. The SLEE als emits an event after an Administratr mdifies an applicatin s prvisined data. An applicatin running in the SLEE. An applicatins running within the SLEE may use events t signal, invke, r cmmunicate with ther applicatins running in the SLEE. Every event in the SLEE has an event type. The event type f an event determines hw the event is ruted t different applicatin cmpnents Event driven applicatins An event driven applicatin typically des nt have an active thread f executin. Typically, an event driven applicatin defines methds that are invked when events are delivered t the applicatin. These methds cntain applicatin cde that inspect the event and perfrm additinal prcessing t handle the JAIN SLEE 1.0 Specificatin, Final Release Page 5

21 Chapter 2 Overview event. The applicatin cde may interact with the resurce that emitted the event r ther resurces, fire new events r update the applicatin state. A cmmn example f an event driven applicatin is an applicatin that implements a state machine. A state machine has states and transitins. A transitin ccurs when there is an ccurrence that causes the state machine t mve frm ne state t anther state. A transitin may be anntated with cmputatin that ccurs during the transitin. When an applicatin implements a state machine, the applicatin s variables determine the state f the state machine, Events represent ccurrences n state transitins, and applicatin cde perfrms cmputatins n transitins. A cmmn way t build an event driven applicatin is t prvide a single event handler methd t receive all events. When the event handler methd receives an event, it inspects the event and directs further prcessing f the event based n the event type. Often this prcessing is delegated t a separate methd fr each event type.the SLEE cmpnent mdel mdels the external interface f an event driven applicatin as a set f events that the applicatin can receive. Each event type is handled by its wn event handler methd. This enfrces a well-defined event interface. The event driven cmpnent mdel allws the SLEE t prvide the event ruting lgic fr the applicatin Applicatin cmpnents The SLEE architecture defines hw an applicatin can be cmpsed f cmpnents. These cmpnents are knwn as Service Building Blck (SBB) cmpnents. Each SBB cmpnent identifies the event types accepted by the cmpnent and has event handler methds that cntain applicatin cde that prcesses events f these event types. In additin, an SBB cmpnent may have an interface fr synchrnus methd invcatins. At runtime, the SLEE creates instances f these cmpnents t prcess events and deletes cmpnents that are n lnger eligible fr event prcessing Prvisined data The SLEE specificatin defines management interfaces and specifies hw applicatins running in the SLEE access prvisined data. Typical prvisined data includes cnfiguratin data r per-subscriber data SLEE Facilities The SLEE specificatin defines a number f Facilities that may be used by SBB cmpnents. These Facilities include the Timer Facility, the Trace Facility, and the Alarm Facility. These facilities prvide access t functinality whse implementatin depends n the particular SLEE implementatin in use. The behaviur f the facilities is specified by this specificatin Resurces and resurce adaptrs A resurce represents a system that is external t a SLEE. Examples include netwrk devices, prtcl stacks, and databases. These resurces may r may nt have Java APIs. Resurces with Java APIs include call agents supprting the Java Call Cntrl API, Parlay/OSA services, varius prtcl stacks and databases supprting the JDBC API. These Java APIs define Java classes r interfaces t represent the events emitted by the resurce. Fr example, the Java Call Cntrl API defines JccCallEvent and JccCnnectinEvent t represent call and cnnectin events. A JccCnnectinEvent signals call events such as cnnectin alerting and cnnectin cnnecting. The SLEE architecture defines hw applicatins running within the SLEE interact with resurces thrugh resurce adaptrs. Resurce adaptrs adapt resurces t the requirements f the SLEE. The SLEE architecture defines the fllwing resurce adaptr cncepts. Resurce adaptr type. A resurce adaptr type declares the cmmn characteristics fr a set f resurce adaptrs. It defines the Java interfaces implemented by the resurce adaptrs f the same resurce adaptr type. JAIN SLEE 1.0 Specificatin, Final Release Page 6

22 Chapter 2 Overview One f these interfaces is knwn as the resurce adaptr interface. It als defines the event types fired by the resurce adaptrs f the same resurce adaptr type. The SLEE specificatin includes nn-nrmative recmmendatins fr the JCC, SIP, and TCAP resurce adaptr types. Typically, a resurce adaptr type is defined by an rganizatin f cllabrating SLEE r resurce vendrs, such as the SLEE expert grup. Resurce adaptr. A resurce adaptr is an implementatin f a particular resurce adaptr type. There may be mu l- tiple implementatins f the same resurce adaptr type. A resurce adaptr cnsists f a set f Java classes and a d eplyment descriptr. It must include a Java class that implements the resurc e adaptr interface f its resurce adaptr type. Typically, a resurce adaptr is prvided either by a resurce vendr r a SLEE vendr t adapt a particular resurce implementatin t a SLEE. It als includes the Java classes f the resurce. Fr example, vendr A that has a JCC resurce may prvide a JCC resurce adaptr (i.e. a resurce adaptr f the JCC resurce adaptr type) r SLEE vendr B may prvide a JCC resurce adaptr that adapts vendr A s JCC resurce t its SLEE. In either case, the JCC resurce adaptr will include the Java classes f the JCC implementatin and the Java classes that adapt the JCC implementatin t the SLEE. Resurce adaptr entity. A resurce adaptr entity is an instance f a resurce adaptr. Multiple resurce adaptr entities may be instantiated frm the same resurce adaptr, Fr exa mple, a JCC resurce adaptr that adapts a SIP-based JCC implementatin t the SLEE may accept IP addresses and prt numbers as parameters. The Administratr may instantiate ne f these JCC resurce adaptrs fr each unique IP address and prt number pair. An imprtant functin f a resurce adaptr entity is t frward events riginating frm the resurce that the resurce adaptr entity represents t the SLEE Event ruting The SLEE specificatin defines hw an event emitted by an event prducer is ruted and delivered t ne r mre c mpnent instances interested in the event. A SLEE has a lgical event ruter. This event ruter receives events emitted frm all event prducers and delivers events t multiple cmpnent instances interested in the event Management interfaces The SLEE architecture defines management interfaces fr managing the SLEE and cmpnents running in the SLEE. These management interfaces enable an Administratr t manage the SLEE, deply and manage applicatins int the SLEE. It includes interfaces fr adding, remving, and mdifying prvisined data Packaging An applicatin is cmpsed frm ne r mre cmpnents. Each cmpnent may cnsist f ne r mre Java class files and deplyment descriptrs. The SLEE specificatin defines hw a cmpnent s Java class files and the cmp nent s deplyment descriptr are aggregated int a deplyable unit. 2.2 Main abstractins The SLEE architecture defines the fllwing cre abstractins and cncepts: Event and event type SBB cmpnent, SBB cmpnent graph, and rt SBB cmpnent SBB entity, SBB entity tree, and rt SBB entity Cascading remval f SBB entity sub-tree SBB abstract class and SBB bject SBB lcal interface and SBB lcal bject Activity, Activity bject, and Activity Cntext JAIN SLEE 1.0 Specificatin, Final Release Page 7

23 Chapter 2 Overview Hw the SLEE reclaims an SBB entity tree and its assciated descendent SBB entities Activity Cntext Interface interface and Activity Cntext Interface bject Prfile, Prfile Table, and Prfile Specificatin Service Deplyable unit Management interface SBB cmpnent An SBB cmpnent defines: Event types received and fired by the SBB cmpnent. Per-instance state. The per-instance state shuld be held in Cntainer Managed Persistent (CMP) fields that can maintain persistent state that shuld persist acrss failures. Event methds. The SBB cmpnent prvides an event handler methd fr each event type received by the SBB cmpnent. The event handler methd cntains applicatin lgic t prcess events f a specific event type. The SBB cmpnent als declares a fire event methd fr each event type fired by the SBB cmpnent. SBB lcal interface methds. The SBB cmpnent declares the SBB lcal interface f the SBB cmpnent. The SBB lcal interface specifies the methds f the SBB cmpnent that may be invked synchrnusly. The SBB lcal interface methds f an SBB cmpnent instance can nly be invked by anther SBB cmpnent instance within the same SBB cmpnent instance tree (see Sectin 2.2.4). The SBB als prvides the implementatin f the methds f the SBB lcal interface. Child relatins. The SBB cmpnent may be related t zer r mre child SBB cmpnents. The SBB cmpnent specifies its child SBB cmpnent relatins. The SBB cmpnent identifies each child SBB cmpnent relatin thrugh a deplyment descriptr element and declares a child relatin accessr methd fr runtime access t this relatin (see Sectin 2.2.2). It als assigns a default event delivery pririty t each child SBB cmpnent (see Sectin 2.2.5). Shareable data. The SBB cmpnent defines the data that it wishes t share with ther cmpnents as a set f Activity Cntext attributes. Each Activity Cntext attribute has a name and a type. These attributes are stred in ne r mre Activity Cntexts (see Chapter 7). An SBB cmpnent defines an SBB Activity Cntext Interface interface that prvides type-safe accessr methds t get and set these attributes. This dcument may als use SBB t refer t an SBB cmpnent SBB graph and rt SBB The SBB develper cmpses SBBs by specifying the child relatins amng SBBs. The parent and the child are the tw rles in a relatin. Lgically, an SBB is a nde in an SBB graph and a child relatin is a directed edge frm the nde f the parent SBB t the nde f the child SBB. Each edge has a label that indicates the default event delivery pririty f the child relatin. Fr example, the SBB develper may develp three cmpnents, the X, Y, and Z SBB. The X SBB may have the Y SBB and the Z SBB as its children. The Y SBB may have the Z SBB as its child. The Z SBB may have Y SBB and itself as its wn children. Figure 1 illustrates this SBB graph. JAIN SLEE 1.0 Specificatin, Final Release Page 8

24 Chapter 2 Overview 15 Y SBB X SBB (rt) A Service -11 B Service 33 SLEE -20 C Service 22 Z SBB (rt) 80 Figure 1 An SBB graph example An SBB may be a parent t zer r mre ther SBBs including itself. In Figure 1, Z is a parent t Y and t itself. At the same time, it can als be a child t zer r mre ther SBB cmpnents including itself. Z is a child t X, Y and itself. A rt SBB is an SBB that may be instantiated by the SLEE t prcess events. A rt SBB must declare a nn-empty set f initial event types that may cause the SLEE t instantiate an instance f the SBB (see 8.5.1). These SBBs are knwn as rt SBBs because their instances may becme rts f SBB entity trees (see Sectin 2.2.4). Typically, a rt SBB represents a cmplete service. Fr example, the SBB develper may develp a CallBlcking SBB and a CallFrwarding SBB t implement the call blcking service and the call frwarding service. These SBBs are rt SBBs since instances f these SBBs may be instantiated t blck and frward calls, respectively. The SBB develper may create a new rt CallBlckingAndFrwarding SBB t implement the call blcking and frwarding service frm the CallBlcking SBB and CallF r- warding SBB. A parent SBB can be related t the same child SBB thrugh multiple relatins. Different pririties may be assigned t these relatins. In the abve Figure, the SLEE is the lgical parent f the all rt SBBs, i.e. there are tw relatins that relate the SLEE as the lgical parent t the X SBB SBB entities An SBB entity is an instance f an SBB cmpnent. An SBB entity is a lgical entity that represents the persistent per-instance state f the instance SBB entity trees and rt SBB entities An SBB entity may create zer r mre SBB entities at runtime. Since an SBB entity may nly be created nce, it has nly a single parent. An SBB entity tree is a directed acyclic graph that represents the child relatins between SBB entities. A nde in this tree represents an SBB entity. A directed edge represents the child relatin frm a parent SBB entity t a child SBB e ntity. The label n the directed edge indicates the event delivery pririty f the child SBB entity relative t the child s siblings (see Sectin 2.2.5). The SLEE will nly create instances f rt SBBs, knwn as rt SBB entities. These SBB entities are rt SBB entities because they are the rt ndes f their respective SBB entity trees. An SBB entity belngs t exactly ne SBB entity tree. JAIN SLEE 1.0 Specificatin, Final Release Page 9

25 Chapter 2 Overview Fr example, the SLEE may instantiate a rt CallBlckingAndFrwarding SBB entity t handle a single call. This SBB entity may subsequently create zer r mre children CallBlcking SBB r CallFrwarding SBB entities t help it handle the call. This SBB entity tree has ne rt CallBlckingAndFrwarding SBB entity and zer 1 r mre directed edges frm the rt SBB entity t its child CallBlcking SBB entities r CallFrwarding SBB entities. T illustrate that a child SBB f a rt SBB may als be a rt SBB in this example, the CallBlcking SBB is als a rt SBB. Hence, the SLEE may als create a rt CallBlcking SBB entity t handle a different call. This SBB entity tree f this rt CallBlcking SBB entity nly cntains the rt CallBlcking SBB entit y. Figure 2 illustrates several SBB entity trees that may be instantiated frm the SBB graph in Figure 1. It als shws the SLEE as the lgical parent f all rt SBB entities. The rt SBB entities in this example are X1, X2, and Z2. X1, Y1, Z1, and Y2 belng t the SBB entity tree rted at X1. X2 belngs t the SBB entity tree rted at X2. Z2, Z3, Y3, Z4, Z5, Z6 belng t the SBB entity tree rted at Z2. 15 Y1-11 X1-20 Z1 20 Y2 SLEE 33 X Z4 Z Z3 80 Z5 Y3 125 Z6 Figure 2 SBB entity trees examples An SBB entity sub-tree is a tree whse rt is a descendent f a rt SBB entity. Fr example, Z3, Z4, and Z5 belng t the SBB entity sub-tree rted at Z Event delivery pririty An event is delivered in rder t each SBB entity that is interested in receiving the event. A parent SBB entity always receives the same event befre its child SBB entities. The event delivery pririty f an SBB entity determines the rder that sibling SBB entities receive the event. The parent SBB specifies a default event delivery pririty fr each child relatin. When a parent SBB entity creates a child SBB entity, the SLEE assigns the default event delivery pririty specified by the child relatin t the child SBB entity. At runtime, the event delivery pririties f SBB entities may be changed. In the SBB trees illustrated by Figure 2, all child SBB entities retain the default event delivery pririty specified by its child relatin, except SBB entity Z4 s pririty has changed t It has zer directed edges befre the rt SBB entity creates any child SBB entities r after it has remved all its child SBB entities. JAIN SLEE 1.0 Specificatin, Final Release Page 10