Jain - Slee 1 - 0 FR Spec

JAIN SLEE 1.
0 Specification,
Final Release
Specification Leads:
Swee Boon Lim

Sun Microsystems, Inc.
David Ferry
Open Cloud Limited
JAIN SLEE 1.0 Specification, Final Release
1/30/2004 - 13:00:00
Copyright 2001-2002 Sun Microsystems, Inc.

901 San Antonio Ave, Palo Alto, CA 94303, USA.
Copyright 2001-2002 Open Cloud Limited

Level 12, Sun Microsystems House, 70 The Terrace, Wellington, New Zealand
All rights reserved

Table of Contents
Table of Contents
Chapter 1 Introduction .......................................................................1
1.1 Target audience.............................................................................................................................. 1
1.2 Typographic and terminology conventions............................................................................... 1
1.3 Acknowledgements....................................................................................................................... 1
1.4 Organization ................................................................................................................................... 2
1.5 Goals ................................................................................................................................................ 3
1.6 Scope ............................................................................................................................................... 3
1.7 Relationship with JAINTM ............................................................................................................ 4
Chapter 2 Overview ............................................................................5

2.1 Scope of the SLEE specification................................................................................................. 5
2.1.1 Component model ......................................................................................................................... 5
2.1.2 Provisioned data............................................................................................................................. 6
2.1.3 SLEE Facilities .............................................................................................................................. 6
2.1.4 Resources and resource adaptors ................................................................................................ 6
2.1.5 Event routing.................................................................................................................................. 7
2.1.6 Management interfaces................................................................................................................. 7
2.1.7 Packaging ........................................................................................................................................ 7
2.2 Main abstractions........................................................................................................................... 7
2.2.1 SBB component............................................................................................................................. 8
2.2.2 SBB graph and root SBB ............................................................................................................. 8
2.2.3 SBB entities .................................................................................................................................... 9
2.2.4 SBB entity trees and root SBB entities...................................................................................... 9
2.2.5 Event delivery priority................................................................................................................10
2.2.6 Cascading removal of SBB entity sub-tree .............................................................................11
2.2.7 SBB object....................................................................................................................................11
2.2.8 SBB local interface and SBB local object...............................................................................11
2.2.9 Activity..........................................................................................................................................11
2.2.10 Activity object..............................................................................................................................12
2.2.11 Activity Context ...........................................................................................................................12
2.2.12 How the SLEE reclaims an SBB entity tree ...........................................................................12
2.2.13 Activity Context reclamation and SBB entity tree removal example .................................13
2.2.14 Activity Context Interface interface and object .....................................................................14
2.2.15 Profile, Profile Table, and Profile Specification ....................................................................14
2.2.16 Service ...........................................................................................................................................15
2.2.17 Service state..................................................................................................................................15
2.2.18 Deployable unit ............................................................................................................................16
2.2.19 Management interface ................................................................................................................17
2.3 Roles ..............................................................................................................................................17
JAIN SLEE 1.0 Specification, Final Release Page iii

Table of Contents
2.3.1 SBB Developer ............................................................................................................................17

2.3.2 Service Deployer .........................................................................................................................17
2.3.3 Administrator...............................................................................................................................17
Chapter 3 Putting it Together ........................................................... 18

3.1 Create an SBB component.........................................................................................................18
3.1.1 Component identity of an SBB component ............................................................................18
3.1.2 Building an SBB from child SBBs ...........................................................................................18
3.1.3 SBB local interface......................................................................................................................19
3.1.4 SBB abstract class .......................................................................................................................19
3.1.5 SBB Activity Context Interface interface ...............................................................................20
3.1.6 SBB Usage Parameters interface..............................................................................................20
3.1.7 Recommended SBB interfaces and classes naming convention.........................................21
3.1.8 SBB deployment descriptor.......................................................................................................21
3.1.9 SBB jar file ...................................................................................................................................26
3.1.10 SBB jar file example ...................................................................................................................27
3.2 Custom event types .....................................................................................................................29
3.2.1 Event type deployment descriptor............................................................................................29
3.2.2 Event type packaging..................................................................................................................29
3.2.3 Event jar file .................................................................................................................................29
3.2.4 Event jar file example .................................................................................................................30
3.3 Profile Specification....................................................................................................................30
3.3.1 Profile CMP interface .................................................................................................................31
3.3.2 Profile Management interface ...................................................................................................31
3.3.3 Profile Management abstract class ...........................................................................................31
3.3.4 Profile Specification deployment descriptor...........................................................................31
3.3.5 Recommended Profile interfaces and classes naming convention......................................32
3.3.6 Profile Specification jar file .......................................................................................................33
3.3.7 Profile Specification jar file example .......................................................................................33
3.4 Create a Service ...........................................................................................................................34
3.4.1 Service deployment descriptor..................................................................................................34
3.4.2 Component identity of a Service...............................................................................................34
3.4.3 Customizing the Service to the operational environment.....................................................35
3.4.4 Packaging the Service for deployment ....................................................................................35
3.4.5 Deploying components ...............................................................................................................36
3.4.6 Deployable unit jar file example...............................................................................................36
3.5 Administer Services and Profiles..............................................................................................36
Chapter 4 Addresses.......................................................................... 38
4.1 Address objects........................................................................................................................38
4.2 AddressPlan objects .............................................................................................................39
4.3 Address string...............................................................................................................................40
JAIN SLEE 1.0 Specification, Final Release Page i v

Table of Contents
4.4 AddressPresentation objects........................................................................................40
4.5 AddressScreening objects................................................................................................41
4.6 Address example ..........................................................................................................................42
Chapter 5 SBB Local Interface ......................................................... 43

5.1 How to obtain an SBB local object ..........................................................................................43
5.2 What can be done with an SBB local object...........................................................................43
5.3 A typical scenario ........................................................................................................................43
5.4 Pass-by-reference semantics......................................................................................................44
5.5 The SbbLocalObject interface ..........................................................................................44
5.5.1 SbbLocalObject interface isIdentical method.....................................................44
5.5.2 SbbLocalObject interface setSbbPriority method .............................................45
5.5.3 SbbLocalObject interface getSbbPriority method .............................................45
5.5.4 SbbLocalObject interface remove method...................................................................45
5.6 The SBB local interface .............................................................................................................46
Chapter 6 The SBB Abstract Class ................................................... 48

6.1 Overview.......................................................................................................................................48
6.1.1 Concrete methods........................................................................................................................48
6.1.2 Abstract methods.........................................................................................................................49
6.2 SBB object life cycle ..................................................................................................................50
6.3 SBB abstract class life cycle methods......................................................................................52
6.3.1 setSbbContext method .......................................................................................................52
6.3.2 unsetSbbContext method..................................................................................................52
6.3.3 sbbCreate method..................................................................................................................52
6.3.4 sbbPostCreate method .......................................................................................................53
6.3.5 sbbActivate method.............................................................................................................53
6.3.6 sbbPassivate method..........................................................................................................54
6.3.7 sbbRemove method..................................................................................................................54
6.3.8 sbbLoad method.......................................................................................................................54
6.3.9 sbbStore method.....................................................................................................................55
6.4 SbbContext interface .............................................................................................................55
6.4.1 SbbContext interface getSbbLocalObject method...............................................56
6.4.2 SbbContext interface getService method...................................................................56
6.4.3 SbbContext interface getSbb method .............................................................................56
6.5 Container Managed Persistence (CMP) ...................................................................................57
6.5.1 CMP field accessor method rules .............................................................................................57
6.5.2 CMP field example......................................................................................................................58
6.6 Non-persistent state.....................................................................................................................59
6.7 SBB abstract class get Profile CMP methods.........................................................................59
6.8 SBB abstract class get child relation methods........................................................................60
JAIN SLEE 1.0 Specification, Final Release Page v

Table of Contents
6.8.1 ChildRelation interface .....................................................................................................61
6.8.2 ChildRelation interface create method .....................................................................61
6.8.3 ChildRelation interface Collection methods.........................................................62
6.8.4 Transactional semantics .............................................................................................................63
6.9 SBB abstract class exception callback method ......................................................................63
6.9.1 RuntimeException handling for transactional methods...............................................64
6.9.2 RuntimeException handling for non-transactional methods.......................................64
6.9.3 SBB abstract class sbbExceptionThrown method........................................................64
6.9.4 SBB abstract class exception callback methods example.....................................................65
6.10 SBB abstract class and SbbContext interface transaction methods..............................65
6.10.1 SBB abstract class sbbRolledBack callback method.....................................................65
6.10.2 SbbContext interface setRollbackOnly method.....................................................66
6.10.3 SbbContext interface getRollbackOnly method.....................................................67
6.10.4 SBB abstract class and SbbContext interface transaction methods example ..............67
6.11 Non-reentrant and re-entrant SBB components .....................................................................68
6.12 Method name restrictions...........................................................................................................68
6.13 SBB component environment ...................................................................................................68
6.13.1 SBB component environment as a JNDI naming context ....................................................69
6.13.2 Resource adaptor type defined Activity Context Interface Factory object references ....72
6.13.3 Resource adaptor object references..........................................................................................73
6.13.4 EJB references..............................................................................................................................75
6.13.5 The SLEE’s responsibility.........................................................................................................75
6.14 Operations allowed in the methods of the SBB abstract class.............................................76
6.15 SBB abstract class methods invoked by the SBB abstract class.........................................76
Chapter 7 Activity Objects, Activity Contexts, and Activity Context

Interface Objects .............................................................. 78
7.1 Relations........................................................................................................................................78
7.1.1 Activity objects and Activity Contexts....................................................................................79
7.1.2 Activity Contexts and Activity Context Interface objects....................................................79
7.1.3 Activity Contexts and SBB entities ..........................................................................................80
7.1.4 Activity Contexts and SLEE Facilities ....................................................................................80
7.2 Activity object..............................................................................................................................80
7.2.1 Sources of Activity objects ........................................................................................................80
7.2.2 Getting an Activity object..........................................................................................................81
7.2.3 Firing events on an Activity object ..........................................................................................81
7.2.4 Firing events on an Activity Context .......................................................................................82
7.2.5 Every Activity object has an end..............................................................................................82
7.2.6 Activity End Event......................................................................................................................82
7.3 Activity Context ...........................................................................................................................82
7.3.1 Activity Context creation ...........................................................................................................83
JAIN SLEE 1.0 Specification, Final Release Page vi

Table of Contents
7.3.2 Activity Context operations.......................................................................................................83

7.3.3 Activity Context state machine .................................................................................................83
7.3.4 Activity and Activity Context end examples..........................................................................85
7.4 Generic ActivityContextInterface interface ........................................................86
7.4.1 ActivityContextInterface interface getActivity method...........................87
7.4.2 ActivityContextInterface interface attach method........................................87
7.4.3 ActivityContextInterface interface detach method........................................88
7.4.4 ActivityContextInterface interface isEnding method...................................88
7.5 SBB Activity Context Interface interface ...............................................................................89
7.5.1 SBB Activity Context Interface get and set accessor methods............................................90
7.6 Getting an Activity Context Interface object..........................................................................90
7.6.1 Activity Context Interface Factory objects .............................................................................90
7.7 Activity Context methods in SBB abstract class and SbbContext................................91
7.7.1 SbbContext interface getActivities method...........................................................92
7.7.2 SBB abstract class asSbbActivityContextInterface method ..........................92
7.8 Activity Context attribute aliasing............................................................................................93
7.8.1 Activity Context attribute aliasing deployment descriptor elements..................................93
7.8.2 Activity Context attribute aliasing example............................................................................93
7.9 Activity Context Naming Facility ............................................................................................94
7.9.1 Activity Context Naming Facility and Activity End Events................................................94
7.10 NullActivity objects...........................................................................................................94
7.10.1 NullActivity interface........................................................................................................95
7.10.2 NullActivityFactory interface.....................................................................................95
7.10.3 NullActivityContextInterfaceFactory interface ..........................................95
7.10.4 All NullActivity methods are transactional...................................................................96
7.10.5 Ending a NullActivity object ...........................................................................................96
7.10.6 JNDI names of NullActivity related objects .................................................................98
7.11 Activity Context and Activity object persistence...................................................................98
Chapter 8 Events ............................................................................... 99

8.1 Overview.......................................................................................................................................99
8.1.1 Event producers ...........................................................................................................................99
8.1.2 Event consumers..........................................................................................................................99
8.1.3 SBB as an event producer and fire event methods................................................................99
8.1.4 SBB as an event consumer and event handler methods......................................................100
8.1.5 Event object................................................................................................................................100
8.1.6 Event class..................................................................................................................................100
8.1.7 Event type ...................................................................................................................................100
8.1.8 Custom event types ...................................................................................................................101
8.1.9 Non-custom event types...........................................................................................................101
8.1.10 Event name .................................................................................................................................102
JAIN SLEE 1.0 Specification, Final Release Page vii

Table of Contents
8.2 Events and Activity Contexts ..................................................................................................102

8.2.1 Firing an event on an Activity Context and a default address...........................................102
8.2.2 Receiving an event on an Activity Context ...........................................................................103
8.3 Event related deployment descriptor elements .....................................................................103
8.3.1 Event producer deployment descriptor elements .................................................................103
8.3.2 Event related SBB deployment descriptor elements ...........................................................104
8.3.3 Feature interaction analysis .....................................................................................................105
8.4 SBB abstract class and SbbContext interface event methods......................................105
8.4.1 SBB abstract class fire event methods...................................................................................105
8.4.2 SBB abstract class event handler methods............................................................................107
8.4.3 SbbContext interface maskEvent and getEventMask methods.........................109
8.5 Event routing..............................................................................................................................111
8.5.1 Initial events ...............................................................................................................................111
8.5.2 Computing the convergence name .........................................................................................112
8.5.3 Selecting convergence name variables ..................................................................................113
8.5.4 Initial event selector method....................................................................................................114
8.5.5 SBB entities ................................................................................................................................116
8.5.6 Concurrency control..................................................................................................................116
8.5.7 Event delivery p riority..............................................................................................................116
8.5.8 Event delivery semantics..........................................................................................................117
8.6 Automatic event subscription..................................................................................................118
8.6.1 Initial event subscription..........................................................................................................118
8.6.2 Received event subscription ....................................................................................................118
8.7 Service Started Event and ServiceActivity objects.................................................119
8.7.1 ServiceActivity objects.................................................................................................119
8.7.2 Ending a ServiceActivity object .................................................................................120
8.7.3 Service Started Events..............................................................................................................120
8.7.4 ServiceActivityFactory interface ...........................................................................120
8.7.5 ServiceActivityContextInterfaceFactory interface ................................121
8.7.6 JNDI names of ServiceActivity related objects .......................................................121
Chapter 9 Transactions ................................................................... 122

9.1 Benefits........................................................................................................................................122
9.2 Atomicity ....................................................................................................................................122
9.3 Isolation.......................................................................................................................................122
9.4 No demarcation API..................................................................................................................122
9.5 Transaction state machine........................................................................................................123
9.5.1 Active state.................................................................................................................................123
9.5.2 Committing state........................................................................................................................123
9.5.3 Committed state.........................................................................................................................124
9.5.4 Marked for Rollback state........................................................................................................124
9.5.5 Rolling Back state .....................................................................................................................124
JAIN SLEE 1.0 Specification, Final Release Page viii

Table of Contents
9.5.6 Rolled Back state.......................................................................................................................124

9.6 Transactional methods..............................................................................................................125
9.6.1 Mandatory transactional methods...........................................................................................125
9.6.2 Required transactional methods..............................................................................................126
9.7 Non-transactional methods ......................................................................................................127
9.7.1 Unspecified transaction context ..............................................................................................127
9.8 SLEE and non-SLEE originated method invocations.........................................................127
9.8.1 Special considerations for cascading removal operations..................................................127
9.8.2 SLEE originated invocation.....................................................................................................128
9.8.3 SLEE originated invocations and transactions .....................................................................130
9.8.4 Examples of valid SLEE originated invocation sequences ................................................130
9.8.5 An illustrated example of a transaction.................................................................................131
9.9 Transactional resources and EJB invocations.......................................................................131
9.10 FIFO ordering of asynchronously fired events.....................................................................132
9.11 Non-transactional resources....................................................................................................132
9.12 Transactions exception handling and rolled back handling ...............................................132
9.12.1 Non-SLEE originated method invocation.............................................................................133
9.12.2 SLEE originated method invocation......................................................................................133
9.12.3 SLEE originated transaction exception and rolled back handling example ....................134
9.12.4 Transaction rolled back callback handling............................................................................135
Chapter 10 Profiles and Profile Specifications.................................. 136

10.1 Introduction................................................................................................................................136
10.1.1 Relationships..............................................................................................................................136
10.1.2 Profile Table names, Profile names, and Profile identifiers...............................................136
10.1.3 Profile Table and Profile addresses ........................................................................................137
10.1.4 Default Profile of a Profile Table ...........................................................................................137
10.2 ProfileID class.....................................................................................................................137
10.3 Profile Table Events and ProfileTableActivity objects ......................................138
10.3.1 ProfileTableActivity objects...................................................................................139
10.3.2 Profile Added Events ................................................................................................................139
10.3.3 Profile Updated Events.............................................................................................................140
10.3.4 Profile Removed Events...........................................................................................................141
10.3.5 ProfileTableActivityContextInterfaceFactory interface .................142
10.4 Profile Specification..................................................................................................................142
10.5 Views of a Profile Specification.............................................................................................143
10.5.1 SBB Developer’s SBB object view ........................................................................................143
10.5.2 SBB Developer’s management view......................................................................................143
10.5.3 Administrator’s view................................................................................................................145
10.6 Profile CMP interface ...............................................................................................................145
10.6.1 Profile references in Profile CMP interface..........................................................................145
10.7 Profile Management interface .................................................................................................145
JAIN SLEE 1.0 Specification, Final Release Page ix

Table of Contents
10.8 Profile Management abstract class .........................................................................................146

10.9 Profile Management objects ....................................................................................................147
10.9.1 Transient state............................................................................................................................147
10.9.2 ProfileManagement interface ........................................................................................147
10.9.3 profileInitialize callback method...........................................................................148
10.9.4 profileLoad callback method...........................................................................................148
10.9.5 profileStore callback method........................................................................................148
10.9.6 profileVerify callback method .....................................................................................148
10.9.7 isProfileDirty and markProfileDirty methods .............................................149
10.9.8 isProfileValid method...................................................................................................149
10.10 Hiding and renaming Profile CMP interface accessor methods........................................149
10.10.1 Uses..............................................................................................................................................150
10.11 A Profile Specification example .............................................................................................150
10.12 Java type usage ..........................................................................................................................151
10.13 Profile Tables referenced by a Service ..................................................................................151
10.13.1 Resource Info Profile Table .....................................................................................................151
10.13.2 Address Profile Table ...............................................................................................................152
10.14 Deployment processing............................................................................................................154
10.15 Profile MBean............................................................................................................................155
10.15.1 Requirements for the Profile MBean interface .....................................................................155
10.15.2 Requirements for the Profile MBean class............................................................................155
10.15.3 ProfileMBean interface......................................................................................................156
10.16 Life cycles...................................................................................................................................158
10.16.1 Life cycle of a Profile ...............................................................................................................158
10.16.2 Life cycle of Profile MBean objects ......................................................................................159
10.17 Profile MBean object management ........................................................................................161
10.17.1 Profile editing.............................................................................................................................161
10.17.2 Management client isolation....................................................................................................161
10.18 SBB object view updates..........................................................................................................161
Chapter 11 Usage Parameters........................................................... 162

11.1 Usage parameter types..............................................................................................................162
11.2 SBB Usage Parameters interface............................................................................................162
11.2.1 Counter-type usage parameter increment method ...............................................................163
11.2.2 Sample-type usage parameter method...................................................................................163
11.2.3 SBB Usage Parameters interface deployment descriptor...................................................163
11.2.4 SBB Usage Parameters interface example ............................................................................164
11.3 SBB usage parameter sets........................................................................................................164
11.3.1 Default SBB usage parameter set ...........................................................................................165
11.3.2 Named SBB usage parameter set............................................................................................165
11.4 Getting access to an SBB usage parameter set .....................................................................165
11.4.1 Get SBB Usage Parameter method.........................................................................................165
JAIN SLEE 1.0 Specification, Final Release Page x

Table of Contents
11.4.2 Get SBB Usage Parameter method example ........................................................................166
Chapter 12 Runtime Environment .................................................... 167

12.1 APIs provided by SLEE ...........................................................................................................167
12.1.1 Java 2 APIs .................................................................................................................................167
12.1.2 SLEE 1.0 APIs ...........................................................................................................................168
12.1.3 JNDI 1.2......................................................................................................................................168
12.2 Programming restrictions.........................................................................................................168
Chapter 13 Facilities ......................................................................... 171

13.1 Timer Facility.............................................................................................................................171
13.1.1 TimerID interface...................................................................................................................171
13.1.2 TimerFacility interface ...................................................................................................172
13.1.3 TimerOptions objects.........................................................................................................174
13.1.4 Delays in delivering Timer Events .........................................................................................177
13.1.5 Timer Events ..............................................................................................................................177
13.1.6 Desired Timer Facility behavior and Timer Facility pseudo code....................................178
13.2 Alarm Facility............................................................................................................................180
13.2.1 AlarmFacility interface ...................................................................................................181
13.2.2 Implementation recommendation...........................................................................................182
13.3 Level objects ...........................................................................................................................182
13.4 Trace Facility..............................................................................................................................183
13.4.1 TraceFacility interface ...................................................................................................184
13.4.2 Implementation recommendation...........................................................................................186
13.5 Activity Context Naming Facility ..........................................................................................186
13.5.1 ActivityContextNamingFacility interface ........................................................187
13.5.2 Conference bridge example .....................................................................................................188
13.6 Profile Facility............................................................................................................................189
13.6.1 ProfileFacility interface..............................................................................................189
13.7 Format of the alarm type and message type string ..............................................................191
13.8 JNDI names of SLEE Facilities ..............................................................................................191
Chapter 14 Management................................................................... 193

14.1 Motivation for JMX instrumentation .....................................................................................193
14.2 SLEE MBean interfaces and classes......................................................................................193
14.2.1 Implementation requirements for a SLEE MBean class.....................................................193
14.2.2 Requirements for the management client..............................................................................194
14.3 Accessing the MBean Server and SLEE MBean objects ...................................................194
14.3.1 Requirements of the Management Client..............................................................................194
14.3.2 Requirements of the SLEE Vendor........................................................................................195
14.3.3 Accessing SLEE MBean objects ............................................................................................195
14.4 SleeProviderFactory class..........................................................................................196
JAIN SLEE 1.0 Specification, Final Release Page xi

Table of Contents
14.4.1 getSleeProvider methods..............................................................................................197
14.5 Vendor implemented SleeProvider concrete class......................................................197
14.6 SleeManagementMBean interface...................................................................................197
14.6.1 Operational states of the SLEE ...............................................................................................198
14.6.2 SleeManagementMBean interface...................................................................................200
14.6.3 SleeState objects.................................................................................................................201
14.6.4 SleeStateChangeNotification class.....................................................................202
14.7 DeploymentMBean interface..............................................................................................202
14.7.1 Components that can be installed...........................................................................................202
14.7.2 Pre-conditions for installing and uninstalling a jar file .......................................................203
14.7.3 Deployable unit identifiers and descriptors...........................................................................203
14.7.4 Component identity...................................................................................................................204
14.7.5 Component identifiers ..............................................................................................................205
14.7.6 Common characteristics of component identifier interfaces..............................................207
14.7.7 Component descriptors.............................................................................................................207
14.7.8 DeploymentMBean interface..............................................................................................210
14.8 ServiceManagementMBean interface ...........................................................................215
14.8.1 ServiceState objects.........................................................................................................217
14.9 ServiceUsageMBean interface ........................................................................................218
14.10 SBB Usage MBean....................................................................................................................221
14.10.1 Requirements for the SBB Usage MBean interface............................................................221
14.10.2 Requirements for the usage parameter accessor method....................................................222
14.10.3 Requirements for the SBB Usage MBean class...................................................................223
14.10.4 SbbUsageMBean interface ...................................................................................................223
14.10.5 UsageNotification class ...............................................................................................224
14.10.6 UsageUpdatedFilter class ......................................................................................225
14.10.7 UsageOutOfRangeFilter class.....................................................................................226
14.10.8 UsageThresholdFilter class .......................................................................................226
14.11 ProfileProvisioningMBean interface......................................................................226
14.11.1 Collection objects..............................................................................................................230
14.12 Alarm Facility management interface....................................................................................231
14.12.1 AlarmMBean interface ...........................................................................................................232
14.12.2 AlarmNotification class ...............................................................................................232
14.12.3 AlarmLevelFilter class..................................................................................................233
14.12.4 AlarmDuplicateFilter class .......................................................................................233
14.12.5 AlarmThresholdFilter class .......................................................................................233
14.13 Trace Facility management interface .....................................................................................234
14.13.1 TraceMBean interface ...........................................................................................................234
14.13.2 TraceNotification class ...............................................................................................235
14.13.3 TraceLevelFilter class..................................................................................................236
JAIN SLEE 1.0 Specification, Final Release Page xii

Table of Contents
14.14 Security........................................................................................................................................237
Chapter 15 Resource Adaptors ......................................................... 238

15.1 Resource adaptor type...............................................................................................................238
15.1.1 Resource adaptor type identifiers ...........................................................................................239
15.1.2 Resource adaptor type deployment descriptor......................................................................240
15.1.3 Resource adaptor type packaging...........................................................................................241
15.1.4 Resource adaptor type jar file ..................................................................................................241
15.1.5 Resource adaptor type jar file example..................................................................................241
15.2 Resource adaptor.......................................................................................................................242
15.2.1 Resource adaptor deployment descriptor..............................................................................243
15.2.2 Resource adaptor packaging....................................................................................................243
15.2.3 Resource adaptor jar file...........................................................................................................243
15.2.4 Resource adaptor jar file example ..........................................................................................244
15.3 Accessing Activity Context Interface Factories from within an SBB..............................244
15.4 Accessing resource objects from within an SBB.................................................................244
15.4.1 Accessing multiple resource adaptor entities........................................................................245
15.4.2 Example code.............................................................................................................................245
15.5 Event delivery semantics on newly created Activity objects.............................................247
15.6 Transaction context propagation.............................................................................................247
15.7 Resource adaptor entity firing an event .................................................................................247
15.8 Resource event filters ................................................................................................................247
15.9 Resource adaptor entity and Activity Context interactions................................................248
Appendix A Event Router Formal Model .......................................... 249

A.1 Notation.......................................................................................................................................249
A.2 Definitions ..................................................................................................................................249
A.2.1 Events ..........................................................................................................................................249
A.2.2 Child relations............................................................................................................................249
A.2.3 SBB Components ......................................................................................................................249
A.2.4 Child relation objects ................................................................................................................250
A.2.5 SBB Entities ...............................................................................................................................250
A.2.6 Services .......................................................................................................................................251
A.2.7 Activity Contexts.......................................................................................................................251
A.3 Further Properties ......................................................................................................................251
A.3.1 Uniqueness of SBB Entities .....................................................................................................251
A.3.2 Convergence names ..................................................................................................................251
A.3.3 Delivered and attached .............................................................................................................251
A.3.4 Descendents and ancestors.......................................................................................................252
A.3.5 Priority of attached SBB entities with respect to an Activity Context and event...........252
A.3.6 Attachment count.......................................................................................................................253
A.3.7 Consistency of child-parent relations.....................................................................................253
JAIN SLEE 1.0 Specification, Final Release Page xiii

Table of Contents
A.3.8 Uniqueness of SBB entities with respect to child relation objects....................................253

A.3.9 Inclusion of child SBB entities in child relation objects.....................................................253
A.3.10 Root SBB entities ......................................................................................................................253
A.3.11 Reachability of existing SBB entities from a root SBB entity...........................................253
A.4 Event queue................................................................................................................................253
A.5 Event routing..............................................................................................................................254
A.5.1 Attach an SBB entity (sbbe) to an Activity Context (ac)...................................................254
A.5.2 Detach an SBB entity (sbbe) from an Activity Context (ac).............................................254
A.5.3 Mask the events ( names ⊆ EventNames ) for an SBB entity (sbbe) on n Activity
Context (ac) ................................................................................................................................255
A.5.4 Remove an SBB entity (sbbe) from a parent SBB entity (p).............................................255
A.5.5 Create a root SBB entity (sbbe) based on a child relation object (cro) belonging to a
Service .........................................................................................................................................255
A.5.6 Create a non-root SBB entity (sbbe) based on a child relation object (cro) belonging to
an SBB entity (p).......................................................................................................................255
A.5.7 Receipt of event (e) on an Activity Context (ac) .................................................................256
A.5.8 Delivery of event (e) on an Activity Context (ac) ...............................................................256
A.5.9 Termination of an Activity Context (ac) ...............................................................................257
A.5.10 On completion of event routing for an event (e)..................................................................257
Appendix B Event Router Pseudo Code............................................. 258

B.1 Definitions ..................................................................................................................................258
B.2 ActivityContextInterface interface attach method pseudo code...............259
B.3 ActivityContextInterface interface detach method pseudo code...............259
B.4 SbbContext interface getActivities method pseudo code..................................260
B.5 SbbContext interface getEventMask method pseudo code ....................................260
B.6 SbbContext interface maskEvent method pseudo code............................................260
B.7 SbbLocalObject interface getSbbPriority method pseudo code ....................260
B.8 SbbLocalObject interface setSbbPriority method pseudo code ....................260
B.9 SbbLocalObject interface remove method pseudo code..........................................260
B.10 ChildRelation interface create method pseudo code ............................................261
B.11 SBB abstract class fire event method pseudo code..............................................................261
B.12 Event router pseudo code.........................................................................................................261
Appendix C JCC Resource Adaptor Type ......................................... 265

C.1 Resource adaptor type identifier.............................................................................................265
C.2 Activity objects..........................................................................................................................265
C.3 Events ..........................................................................................................................................265
C.3.1 Event types .................................................................................................................................266
C.3.2 Event classes...............................................................................................................................266
C.4 Activity Context Interface Factory interface ........................................................................266
C.5 Resource adaptor object...........................................................................................................266
JAIN SLEE 1.0 Specification, Final Release Page xiv

Table of Contents
C.6 Restrictions.................................................................................................................................266
Appendix D JAIN SIP Resource Adaptor Type ................................. 267

D.1 Resource Adaptor type identifier............................................................................................267
D.2 Activity objects..........................................................................................................................267
D.3 Events ..........................................................................................................................................267
D.3.1 Event types .................................................................................................................................268
D.3.2 Event classes...............................................................................................................................268
D.4 Activity Context Interface Factory interface ........................................................................268
D.5 Resource adaptor object...........................................................................................................268
D.6 Restrictions.................................................................................................................................269
Appendix E JAIN TCAP Resource Adaptor Type............................. 270

E.1 Resource adaptor type identifier.............................................................................................270
E.2 Activity objects..........................................................................................................................270
E.3 Events ..........................................................................................................................................270
E.3.1 Event types .................................................................................................................................271
E.3.2 Event classes...............................................................................................................................271
E.4 Activity Context Interface Factory interface ........................................................................271
E.5 Resource adaptor object...........................................................................................................272
E.6 Restrictions.................................................................................................................................272
Appendix F Integration with EJB applications.................................. 273

F.1 Invoking an EJB ........................................................................................................................273
F.1.1 Example code.............................................................................................................................273
F.2 Passing an event to SLEE ........................................................................................................273
F.2.1 Example code.............................................................................................................................274
Appendix G Frequently Asked Questions........................................... 276

G.1 Persistence..................................................................................................................................276
G.2 SLEE event model versus JavaBeans listener model ..........................................................276
G.3 SLEE originated invocation vs. non-SLEE originated invocation design.......................277
G.4 Writing a sbbRolledBack method...........................................................................................277
Glossary ........................................................................................ 279
JAIN SLEE 1.0 Specification, Final Release Page xv

Chapter 1
Introduction
Chapter 1 Introduction
This is the specification of the JAIN TM Service Logic and Execution Environment (SLEE) architecture.
This architecture defines a component model for structuring the application logic of communications appli-
cations as a collection of reusable object-oriented components, and for composing these components into
more sophisticated services. The SLEE architecture also defines the contract between these components
and the container that will host these comp onents at runtime.
The SLEE specification supports the development of highly available and scaleable distributed SLEE
specification compliant application servers, but does not mandate any particular impleme ntation strategy.
More importantly, applications may be written once, and then deployed on any application server that com-
plies with the SLEE specification.
In addition to the application component model, the SLEE specification also defines the management inter-
faces used to administer the application server and the application components executing within the appli-
cation server. It also defines a set of standard Facilities, like the Timer Facility, Trace Facility, and Alarm
Facility.
1.1 Target audience

The target audiences for this specification are communication application developers, vendors of the com-
munication application servers, and telecommunications product vendors in the areas of Softswitches, SIP
Proxy servers, Call Agents, and traditional class 4 or 5 switches who wish to deploy services on their prod-
uct which are developed by service creators following the JAIN SLEE specification.
1.2 Typographic and terminology conventions

The SLEE specification uses the following typographic conventions:
• Logical Entity.
Words with the first character capitalized describe a logical or conceptual entity defined by the
SLEE specification, e.g. Activity, Activity Context, SBB, Service, Profile, and Profile Table.
• InterfaceOrClass.
A single word in a fixed width font and made up of concatenated words, with the first
character of each word capitalized, identifies a Java class or interface, e.g. the TimerID interface,
the CallBlockingSbb abstract class and the FooService abstract class.
• deployment-descriptor-element.
A single word in a fixed width font and made up of lowercase word(s) joined by a h yphen
identifies a deployment descriptor element, e.g. sbb, sbb-classes, sbb-abstract-
class-name.
The SLEE specification uses the following terminology conventions:
• “<entity> entity” refers to an instance of a logical or conceptual entity, e.g. an SBB entity.
• “<entity> object” refers to a Java object that represents an entity and provides the entity with a
Java object that can be invoked to manipulate the entity, e.g. Activity object.
• “<class> object” refers to a Java object and this Java object is an instance of the specified
class, e.g. a CallBlockingSbb object, a FooService object.
• “<interface> object” refers to a Java object and this Java object implements the specified in-
terface, e.g. a TimerID object.
1.3 Acknowledgements
The JAIN SLEE architecture is a broad effort that includes contributions from numerous people at Sun,
Open Cloud, and at partner companies.
JAIN SLEE 1.0 Specification, Final Release Page 1

Chapter 1
Introduction
We acknowledge Phelim O’Doherty of Sun, David Page, Steven Adams, Koryn Grant, Oliver Jowett, Ben
Evans, Matthew Hutton, Catherine Allen and Nick Earle of Open Cloud for their valuable direct contribu-
tions. They wrote and edited many chapters and appendices in this document and provided much needed
critical reviews.
We thank the members of the JAIN SLEE Expert Group for their contributions to this specification. The
expert group members include: Chammika Subasinghe of Fujitsu, Gal Shachor, Shmuel Kallner, Joe McIn-
tyre of IBM, Anders Lundqvist and Mickael Larsson of Incomit, Herb Ca lhoun of Motorola, John Storrie of
Nortel Networks, Atsuyoshi Shirato, Shinji Tanaka and Hideki Shina of NTT, Yaron Sheffer and Teddy
Pardo of Personeta, Ulf Lange of Siemens, and Ramana Devarapalli and Stuart Broad of TrueTel Commu-
nications, Michael Maretzke of Vodafone.
We thank Subodh Bapat, Charlie Tierney, Rob Goedman, and Margaret Nilson of Sun, and David Long of
Open Cloud for their enthusiastic support and continuing to dedicate valuable resources to this effort
throughout its long gestation process.
We thank Douglas Tait, Steven Grover, and Gary Bruce of the JAIN team for their tireless effort in promot-
ing JAIN, and more specifically, the JAIN SLEE.
We also thank Vlada Matena and Mark Hapner of the Sun Microsystems J2EE team for sharing their exper-
tise in comp onent models and application server architectures.
1.4 Organization
This document is divided up into several chapters as follows:
• Chapter 2, ‘Overview’ discusses at a high level each of the concepts required in order to under-
stand the JAIN SLEE architecture.
• Chapter 3, ‘Putting it Together’ discusses how a developer would implement a Service Building
Block (SBB) component, compose SBB components into higher level SBB components and Ser-
vice components, define components for custom event types and provisioned data, deploy and
administer Service components.
• Chapter 4, ‘Addresses ’ discusses addresses.
• Chapter 5, ‘SBB Local Interface’ discusses how an SBB component defines its local interface that
is used by other SBBs to invoke this SBB in a synchronous manner.
• Chapter 6, ‘The SBB Abstract Class’ discusses the SBB abstract class and the life cycle of its in-
stances.
• Chapter 7, ‘Activity Objects, Activity Contexts, and Activity Context Interface Objects’ discusses
Activities and Activity objects, how Activities are represented in the SLEE by Activity Contexts,
the Activity Context Interface objects that expose the attributes of an Activity Context and the re-
lationships of these objects to other objects and entities.
• Chapter 8, ‘Events’ discusses the SLEE event architecture, defining events, and the semantics of
firing and receiving events.
• Chapter 9, ‘Transactions’ discusses how the SLEE uses well-established transaction concepts to
respond to unexpected failures during execution.
• Chapter 10, ‘Profiles and Profile Specifications’ discusses defining the schema and behavior of
Profiles using Profile Specifications, the classes and interfaces that implement these Profile Speci-
fications, and the life cycle of instances of these classes.
• Chapter 11, ‘Usage Parameters’ discusses defining counters and sample sets that are updated by
SBB components and the operations available to manage usage parameter sets and the data con-
tained within them.
• Chapter 12, ‘Runtime Environment’ discusses the application programming interfaces provided by
the SLEE at runtime and the restrictions that the SLEE imposes on components running in the
SLEE.

Chapter 1
Introduction
• Chapter 13, ‘Facilities’ discusses the standard Facilities defined by the SLEE specification.
• Chapter 14, ‘Management’ discusses the management interfaces exposed by the SLEE inclu ding
those for subscription management, Service management, and management of the SLEE Facilities.
• Chapter 15, ‘Resource Adaptors’ discusses resources, resource types, and how resources interact
with the SLEE.
• Appendix A, ‘Event Router Formal Model’ discusses the desired behavior of the SLEE event
router with a formal mathematical specification.
• Appendix B, ‘Event Router Pseudo Code’ discusses the desired behavior of the SLEE event router
using pseudo code.
• Appendix C, ‘JCC Resource Adaptor Type’ discusses the recommended way to adapt and plug
JCC resources into the SLEE.
• Appendix D, ‘JAIN SIP Resource Adaptor Type’ discusses the recommended way to adapt and
plug JAIN SIP resources into the SLEE.
• Appendix E, ‘JAIN TCAP Resource Adaptor Type’ discusses the re commended way to adapt and
plug JAIN TCAP resources into the SLEE.
• Appendix F, ‘ Integration with EJB applications’ discusses the recommended way to integrate
JAIN SLEE with Enterprise JavaBeans
1.5 Goals
The JAIN Service Logic and Execution Environment (SLEE) architecture has the following goals:
• Define the standard component architecture for building distributed object-oriented communica -
tions applications in the Java™ programming language.
• Allow the development of distributable communication applications by combining components
developed using tools from different vendors.
• Support simple application development. Application developers wi ll not have to understand low-
level transaction and state management details, multi-threading, connection pooling, and other
complex low-level APIs.
• Adopt the Write Once, Run Anywhere™ philosophy of the Java programming language. Applica-
tion components can be developed once, and then deployed on multiple platforms without recom-
pilation or source code modification.
• Address the development, deployment, and runtime aspects of a communications application’s life
cycle.
• Define the interfaces that enable communication applications from multiple vendors to develop
and deploy components that can interoperate at runtime.
• Compatible with the Enterprise JavaBeans (EJB) specification and the Java Naming and Directory
Interface (JNDI) specification. SLEE vendors should be able build an implementation of the SLEE
specification on an EJB 2.0 compliant J2EE implementation. J2EE vendors may also choose to ex-
tend their existing EJB servers to support JAIN SLEE applications.
• Compatible with the Java Management Extensions (JMX) specification. JMX can be used as an
instrument that can be controlled by a JMX server.
• Compatible with other Java programming language APIs.
1.6 Scope
The first version of the JAIN SLEE specification deals with commonly used functions that are routinely
required in an execution platform, where application developers need to provide the application logic. This

Chapter 1
Introduction
typical functionality deals with the application life cycle – installation, management and execution - and the
framework under which the applications run.
This specification does not address the connection of external resources, such as protocol stacks, to the
SLEE. This interface will be addressed in a subsequent revision.
1.7 Relationship with JAINTM

The JAINTM APIs for Integrated Networks bring service portability, convergence, and secure network ac-
cess to telephony and data networks. By providing a new level of abstraction and associated Java interfaces
for service creation across Public Switched Telephone Network (PSTN), packet (e.g. Internet Protocol (IP)
or Asynchronous Transfer Mode (ATM)) and wireless networks, JAIN technology enables the integration of
Internet and Intelligent Network (IN) protocols. This is referred to as Integrated Networks. Furthermore, by
allowing Java applications to have secure access to resources inside the network, the opportunity is created
to deliver thousands of services rather than the dozens currently available. Thus, JAIN technology is chang-
ing the communications market from many proprietary closed systems to a single network architecture
where services can be rapidly created and deployed.
The JAIN Service Logic Execution Environment (SLEE) is an integral part of the set of JAIN API’s. It
function is of core importance, it is the logic and execution environment in which communication applica-
tions are deployed to utilize the various network resources defined by the other JAIN API’s. In essence, the
JAIN SLEE specification defines interfaces and requirements for communication applications within a car-
rier grade communications platform utilizing other JAIN and non-JAIN communication standards.

Chapter 2
Overview
Chapter 2 Overview
A SLEE is an application server. This application server is a container for software comp onents. The SLEE
specification is designed and optimized for event driven applications.
The SLEE specification is targeted at users of a SLEE. These users include the developer of software com-
ponents running on the SLEE and Administrators managing the software comp onents deployed on the
SLEE.
This specification does not specify how a SLEE vendor should implement a SLEE and the underlying tech-
nology. Multiple implementation choices allow multiple SLEE vendors to differentiate their products and
to ensure diversity in the SLEE market.
2.1 Scope of the SLEE specification

The SLEE specification specifies:
• The SLEE component model and how it supports event driven applications as SLEE components.
• How SLEE components can be composed and invoke each other.
• How provisioned data is specified, externally managed and accessed by SLEE components.
• SLEE Facilities.
• How resources fit into the SLEE architecture and how SLEE applications interact with these re-
sources.
• How events are routed to application components.
• The management interfaces of a SLEE.
• How applications are packaged for deployment into a SLEE.
2.1.1 Component model

The SLEE component model is targeted at event driven applications, also known as asynchronous applica-
tions. These applications receive requests in the form of events.
2.1.1.1 Events and event types

An event represents an occurrence that requires application processing. It carries information that describes
the occurrence, such as the source of the event. An event may originate from:
• An external resource such as a communications protocol stack.
• Within the SLEE.
The SLEE uses events to communicate changes in the SLEE that may be of interest to applica-
tions running in the SLEE. For example, the Timer Facility emits an event when a timer has ex-
pired. The SLEE also emits an event after an Administrator modifies an application’s provisioned
data.
• An application running in the SLEE.
An applications running within the SLEE may use events to signal, invoke, or communicate with
other applications running in the SLEE.
Every event in the SLEE has an event type. The event type of an event determines how the event is routed
to different application components.
2.1.1.2 Event driven applications

An event driven application typically does not have an active thread of execution. Typically, an event
driven application defines methods that are invoked when events are delivered to the application. These
methods contain application code that inspect the event and perform additional processing to handle the
Chapter 2
Overview
event. The application code may interact with the resource that emitted the event or other resources, fire
new events or update the application state.
A common example of an event driven application is an application that implements a state machine. A
state machine has states and transitions. A transition occurs when there is an occurrence that causes the
state machine to move from one state to another state. A transition may be annotated with computation that
occurs during the transition.
When an application implements a state machine, the application’s variables determine the state of the state
machine, Events represent occurrences on state transitions, and application code performs computations on
transitions.
A common way to build an event driven application is to provide a single event handler method to receive
all events. When the event handler method receives an event, it inspects the event and directs further proc-
essing of the event based on the event type. Often this processing is delegated to a separate method for
each event type.The SLEE component model models the external interface of an event driven application
as a set of events that the application can receive. Each event type is handled by its own event handler
method. This enforces a well-defined event interface. The event driven component model allows the SLEE
to provide the event routing logic for the application.
2.1.1.3 Application components

The SLEE architecture defines how an application can be composed of components. These components are
known as Service Building Block (SBB) components.
Each SBB component identifies the event types accepted by the component and has event handler methods
that contain application code that processes events of these event types. In addition, an SBB component
may have an interface for synchronous method invocations.
At runtime, the SLEE creates instances of these components to process events and deletes components that
are no longer eligible for event processing.
2.1.2 Provisioned data

The SLEE specification defines management interfaces and specifies how applications running in the SLEE
access provisioned data. Typical provisioned data includes configuration data or per-subscriber data.
2.1.3 SLEE Facilities

The SLEE specification defines a number of Facilities that may be used by SBB components. These Facili-
ties include the Timer Facility, the Trace Facility, and the Alarm Facility. These facilities provide access to
functionality whose implementation depends on the particular SLEE implementation in use. The behaviour
of the facilities is specified by this specification.
2.1.4 Resources and resource adaptors

A resource represents a system that is external to a SLEE. Examples include network devices, protocol
stacks, and databases. These resources may or may not have Java APIs. Resources with Java APIs include
call agents supporting the Java Call Control API, Parlay/OSA services , various protocol stacks and data-
bases supporting the JDBC API. These Java APIs define Java classes or interfaces to represent the events
emitted by the resource. For example, the Java Call Control API defines JccCallEvent and JccCon-
nectionEvent to represent call and connection events. A JccConnectionEvent signals call events
such as connection alerting and connection connecting.
The SLEE architecture defines how applications running within the SLEE interact with resources through
resource adaptors. Resource adaptors adapt resources to the requirements of the SLEE. The SLEE architec-
ture defines the following resource adaptor concepts.
• Resource adaptor type.
A resource adaptor type declares the common characteristics for a set of resource adaptors. It de-
fines the Java interfaces implemented by the resource adaptors of the same resource adaptor type.
Chapter 2
Overview
One of these interfaces is known as the resource adaptor interface. It also defines the event types
fired by the resource adaptors of the same resource adaptor type. The SLEE specification includes
non-normative recommendations for the JCC, SIP, and TCAP resource adaptor types. Typically, a
resource adaptor type is defined by an organization of collaborating SLEE or resource vendors,
such as the SLEE expert group.
• Resource adaptor.
A resource adaptor is an implementation of a particular resource adaptor type. There may be mu l-
tiple implementations of the same resource adaptor type. A resource adaptor consists of a set of
Java classes and a d eployment descriptor. It must include a Java class that implements the resourc e
adaptor interface of its resource adaptor type. Typically, a resource adaptor is provided either by a
resource vendor or a SLEE vendor to adapt a particular resource implementation to a SLEE. It also
includes the Java classes of the resource. For example, vendor A that has a JCC resource may pro-
vide a JCC resource adaptor (i.e. a resource adaptor of the JCC resource adaptor type) or SLEE
vendor B may provide a JCC resource adaptor that adapts vendor A’s JCC resource to its SLEE.
In either case, the JCC resource adaptor will include the Java classes of the JCC implementation
and the Java classes that adapt the JCC implementation to the SLEE.
• Resource adaptor entity.
A resource adaptor entity is an instance of a resource adaptor. Multiple resource adaptor entities
may be instantiated from the same resource adaptor, For exa mple, a JCC resource adaptor that
adapts a SIP-based JCC implementation to the SLEE may accept IP addresses and port numbers as
parameters. The Administrator may instantiate one of these JCC resource adaptors for each unique
IP address and port number pair. An important function of a resource adaptor entity is to forward
events originating from the resource that the resource adaptor entity represents to the SLEE.
2.1.5 Event routing

The SLEE specification defines how an event emitted by an event producer is routed and delivered to one
or more co mponent instances interested in the event. A SLEE has a logical event router. This event router
receives events emitted from all event producers and delivers events to multiple component instances inter-
ested in the event.
2.1.6 Management interfaces

The SLEE architecture defines management interfaces for managing the SLEE and components running in
the SLEE. These management interfaces enable an Administrator to manage the SLEE, deploy and manage
applications into the SLEE. It includes interfaces for adding, removing, and modifying provisioned data.
2.1.7 Packaging
An application is composed from one or more components. Each component may consist of one or more
Java class files and deployment descriptors. The SLEE specification defines how a component’s Java class
files and the comp onent’s deployment descriptor are aggregated into a deployable unit.
2.2 Main abstractions

The SLEE architecture defines the following core abstractions and concepts:
• Event and event type
• SBB component, SBB component graph, and root SBB component
• SBB entity, SBB entity tree, and root SBB entity
• Cascading removal of SBB entity sub-tree
• SBB abstract class and SBB object
• SBB local interface and SBB local object
• Activity, Activity object, and Activity Context
Chapter 2
Overview
• How the SLEE reclaims an SBB entity tree and its associated descendent SBB entities
• Activity Context Interface interface and Activity Context Interface object
• Profile, Profile Table, and Profile Specification
• Service
• Deployable unit
• Management interface
2.2.1 SBB component

An SBB component defines:
• Event types received and fired by the SBB component.
• Per-instance state.
The per-instance state should be held in Container Managed Persistent (CMP) fields that can
maintain persistent state that should persist across failures.
• Event methods.
The SBB component provides an event handler method for each event type received by the SBB
component. The event handler method contains application logic to process events of a specific
event type. The SBB component also declares a fire event method for each event type fired by the
SBB component.
• SBB local interface methods.
The SBB component declares the SBB local interface of the SBB component. The SBB local in-
terface specifies the methods of the SBB component that may be invoked synchronously. The
SBB local interface methods of an SBB component instance can only be invoked by another SBB
component instance within the same SBB component instance tree (see Section 2.2.4). The SBB
also provides the imple mentation of the methods of the SBB local interface.
• Child relations.
The SBB component may be related to zero or more child SBB components. The SBB component
specifies its child SBB component relations. The SBB component identifies each child SBB com-
ponent relation through a deployment descriptor element and declares a child relation accessor
method for runtime access to this relation (see Section 2.2.2). It also assigns a default event deliv-
ery priority to each child SBB component (see Section 2.2.5).
• Shareable data.
The SBB component defines the data that it wishes to share with other components as a set of Ac-
tivity Context attributes. Each Activity Context attribute has a name and a type. These attributes
are stored in one or more Activity Contexts (see Chapter 7). An SBB component defines an SBB
Activity Context Interface interface that provides type-safe accessor methods to get and set these
attributes.
This document may also use SBB to refer to an SBB component.
2.2.2 SBB graph and root SBB

The SBB developer composes SBBs by specifying the child relations among SBBs. The parent and the
child are the two roles in a relation. Logically, an SBB is a node in an SBB graph and a child relation is a
directed edge from the node of the parent SBB to the node of the child SBB. Each edge has a label that
indicates the default event delivery priority of the child relation.
For example, the SBB developer may develop three components, 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 own children. Figure 1 illustrates this SBB graph.

Chapter 2
Overview
15
Y SBB
X SBB
20 125
(root)
-20
Z SBB
B Service (root)
33
C Service
A Service 22
80
-11
SLEE
Figure 1 An SBB graph example

An SBB may be a parent to zero or more other SBBs including itself. In Figure 1, Z is a parent to Y and to
itself. At the same time, it can also be a child to zero or more other SBB components including itself. Z is a
child to X, Y and itself.
A root SBB is an SBB that may be instantiated by the SLEE to process events. A root SBB must declare a
non-empty set of initial event types that may cause the SLEE to instantiate an instance of the SBB (see
8.5.1). These SBBs are known as root SBBs because their instances may become roots of SBB entity trees
(see Section 2.2.4).
Typically, a root SBB represents a “complete service”. For example, the SBB developer may develop a
CallBlocking SBB and a CallForwarding SBB to implement the “call blocking” service and the “call for-
warding” service. These SBBs are root SBBs since instances of these SBBs may be instantiated to block
and forward calls, respectively. The SBB developer may create a new root CallBlockingAndForwarding
SBB to implement the “call blocking and forwarding” service from the CallBlocking SBB and CallFo r-
warding SBB.
A parent SBB can be related to the same child SBB through multiple relations. Different priorities may be
assigned to these relations. In the above Figure, the SLEE is the logical parent of the all root SBBs, i.e.
there are two relations that relate the SLEE as the logical parent to the X SBB.
2.2.3 SBB entities

An SBB entity is an instance of an SBB component. An SBB entity is a logical entity that represents the
persistent per-instance state of the instance.
2.2.4 SBB entity trees and root SBB entities

An SBB entity may create zero or more SBB entities at runtime. Since an SBB entity may only be created
once, it has only a single parent.
An SBB entity tree is a directed acyclic graph that represents the child relations between SBB entities. A
node in this tree represents an SBB entity. A directed edge represents the child relation from a parent SBB
entity to a child SBB e ntity. The label on the directed edge indicates the event delivery priority of the child
SBB entity relative to the child’s siblings (see Section 2.2.5).
The SLEE will only create instances of root SBBs, known as root SBB entities. These SBB entities are root
SBB entities because they are the root nodes of their respective SBB entity trees. An SBB entity belongs to
exactly one SBB entity tree.

Chapter 2
Overview
For example, the SLEE may instantiate a root CallBlockingAndForwarding SBB entity to handle a single
call. This SBB entity may subsequently create zero or more children CallBlocking SBB or CallForwarding
SBB entities to help it handle the call. This SBB entity tree has one root CallBlockingAndForwarding SBB
entity and zero 1 or more directed edges from the root SBB entity to its child CallBlocking SBB entities or
CallForwarding SBB entities.
To illustrate that a child SBB of a root SBB may also be a root SBB in this example, the CallBlocking SBB
is also a root SBB. Hence, the SLEE may also create a root CallBlocking SBB entity to handle a different
call. This SBB entity tree of this root CallBlocking SBB entity only contains the root CallBlocking SBB
entit y.
Figure 2 illustrates several SBB entity trees that may be instantiated from the SBB graph in Figure 1. It also
shows the SLEE as the “logical parent” of all root SBB entities. The root SBB entities in this example are
X1, X2, and Z2. X1, Y1, Z1, and Y2 belong to the SBB entity tree rooted at X1. X2 belongs to the SBB
entity tree rooted at X2. Z2, Z3, Y3, Z4, Z5, Z6 belong to the SBB entity tree rooted at Z2.
15 Y1
X1 -20
-11
Z1 20
Y2
33 X2
SLEE
22 82 Z4
80 Z3 80
Z2 20 Z5
Y3 125
Z6
Figure 2 SBB entity trees examples

An SBB entity sub-tree is a tree whose root is a descendent of a root SBB entity. For example, Z3, Z4, and
Z5 belong to the SBB entity sub-tree rooted at Z3.
2.2.5 Event delivery priority

An event is delivered in order to each SBB entity that is interested in receiving the event. A parent SBB
entity always receives the same event before its child SBB entities. The event delivery priority of an SBB
entity determines the order that sibling SBB entities receive the event.
The parent SBB specifies a default event delivery priority for each child relation. When a parent SBB entity
creates a child SBB entity, the SLEE assigns the default event delivery priority specified by the child rela -
tion to the child SBB entity. At runtime, the event delivery priorities of SBB entities may be changed. In
the SBB trees illustrated by Figure 2, all child SBB entities retain the default event delivery priority speci-
fied by its child relation, except SBB entity Z4’s priority has changed to 82.
1
It has zero directed edges before the root SBB entity creates any child SBB entities or after it has removed all its child SBB entities.
Chapter 2
Overview
2.2.6 Cascading removal of SBB entity sub-tree

An SBB entity can be removed by invoking the remove method on the SbbLocalObject interface or via the
ChildRelationObject interface. When this occurs, the SLEE performs the necessary operations to remove
the SBB entity and all the SBB entity’s d escendents, i.e. the SLEE removes the sub-tree rooted at the SBB
entity targeted for removal. This mechanism exists to ensure that SBB entities are not ‘leaked’ due to lost
references to a particular SBB entity in SBB code2 .
When t he SLEE removes a sub-tree, it performs a pre-order traversal of the sub-tree to delete the SBB enti-
ties in the sub-tree. It deletes the parent SBB entity before it deletes the child SBB entities. The SLEE does
not specify the order in which sibling SBB entities are deleted. When the SLEE removes an SBB entity, the
SLEE invokes the appropriate life cycle methods (see Section 6.3) on any SBB objects that cache the SBB
entity’s state and the SLEE detaches the SBB entity from all Activity Contexts (see Section 7.3.3) .
In Figure 2, if X1 is removed, X1 is deleted before Y1 and Z1. Y1 may be de leted before Z1 or Z1 may be
deleted before Y1. After Z1 is deleted, Y2 is deleted. The end result is that the sub-tree rooted at X1 is re -
moved.
2.2.7 SBB object

An SBB object is an instance of the SLEE generated class that extends the SBB abstract class (see Section
3.1.4). The SBB abstract class is the SBB Developer provided Java class that contains the definitions and
methods listed above.
The SLEE creates and manages a pool of SBB objects. At runtime, the SLEE may assign zero 3 or more
SBB objects to represent an SBB entity. When an SBB object is assigned to represent an SBB entity, the
SBB object is in the Ready state (see Section 6.3). It can receive and fire events, receive synchronous
method invocations, and access and update the persistent state of the SBB entity. Another viewpoint is that
the SBB object caches a copy of the persistent data of the SBB entity to provide transactional semantics
(see Chapter 9).
2.2.8 SBB local interface and SBB local object

Each SBB has an SBB local interface. The SBB local interface of an SBB is either an SBB specific local
interface provided by the SBB Developer that extends the SbbLocalObject interface, or the SbbLo-
calObject interface if the SBB Developer did not provide an SBB specific local interface.
An SBB object synchronously invokes the SBB object of a target SBB entity through an SBB local object.
The SBB local object is a SLEE implemented object that implements the SBB local interface and repre-
sents the target SBB entity. When the SBB object invokes an SBB Developer defined method on the SBB
local object, the corresponding method in the SBB abstract class that i mplements this method is invoked on
an SBB object that represents the target SBB entity’s state. Another viewpoint is that the SBB local object
is a client side stub object for synchronous method invocations.
Logically, an SBB local object represents only one SBB entity, but zero or more SBB local objects may
represent the same SBB entity.
An SBB object is only allowed to invoke SBB local objects that represent SBB entities in the same SBB
entity tree. The execution behavior of the SLEE is undefined if an SBB object attempts to invoke an SBB
local object that represents an SBB entity that is not in the same SBB entity tree.
2.2.9 Activity
An Activity represents a related stream of events. These events represent occurrences of significance that
have occurred on the entity represented by the Activity. From a resource’s perspective, an Activity repre-
sents an entity within the resource that emits events on state changes within the entity or resource.
2
JVM garbage collection does not solve this problem as SBB entity state is not directly related to instances of SBB objects.
3
The SBB entity exists but the SLEE may not assign an SBB object to the SBB entity until the SBB entity is invoked.
Chapter 2
Overview
For example, a phone call may be an Activity.
2.2.10 Activity object

An Activity object is a Java object that encapsulates an Activity and may provide methods that are used to
interact with the Activity. Each resource adaptor type may define one or more types of Activity objects. In
most cases, Activity objects are created and owned by resource adaptor entities.
For example, a JccCall object is an Activity object that represents a phone call (which is the Activity).
2.2.11 Activity Context

The SLEE uses an Activity Context to represent and encapsulate an underlying Activity object within the
SLEE. An Activity Context is a logical entity within the SLEE. It does not have a visible Java API. There is
a one-to-one relationship between an Activity object and an Activity Context.
• An Activity Context is also a store for attributes that may be shared by multiple SBB entities that
interact with the Activity object represented by the Activity Context. These SBB entities can read
and modify attributes stored in the Activity Context.
• An Activity Context is also an event channel that accepts events fired on the Activity Context and
distributes these events to the SBB entities attached to the Activity Context. An SBB entity can
invoke other SBB entities in an asynchronous manner by firing events on the Activity Context.
An SBB entity may be attached to one or more Activity Contexts. An SBB e ntity can only receive events
fired on Activity Contexts that it is attached to.
The SLEE does not count the number of times an SBB entity is attached or detached from an Activity Con-
text. The SBB entity is either attached to the Activity Context or not. Attaching multiple times consecu-
tively is the same as attaching once and detaching multiple times is the same as detaching once.
The SLEE attaches and detaches SBB entities from Activity Contexts in the following situations.
• When a new root SBB entity is created to process its initial event, the SLEE attaches the new root
SBB entity to the Activity Context on which the in itial event was fired (see Section 8.5).
• After the underlying Activity object of an Activity Context ends, the SLEE detaches SBB entities
attached to the Activity Context (see Section 7.3.3).
• Before the SLEE removes an SBB entity as part of a cas cading removal of an SBB entity sub-tree,
the SLEE detaches the SBB entity from all Activity Contexts.
An SBB entity may also explicitly invoke methods to change which Activity Contexts it or other SBB enti-
ties in the same SBB entity tree are attached to by explicitly attaching those SBB entities to these Activity
Contexts or by explicitly detaching those SBB entities from these Activity Co ntexts. For example,
• An SBB entity may attach itself to the Activity Context of a new Activity object that it has cre-
ated. This allows the SBB entity to receive events fired on the Activity Context by the newly cre-
ated Activity object.
• An SBB entity may detach itself from an Activity Context if it no longer wants to receive events
fired on that Activity Context.
• An SBB entity may explicitly attach another SBB entity to an Activity Co ntext. This functionality
allows the delegation of all or some processing of events fired on the Activity Co ntext to another
SBB entity.
2.2.12 How the SLEE reclaims an SBB entity tree

The SLEE uses the attachment count mechanism to remove SBB entity trees that are no longer attached to
any Activity Contexts and hence will no longer be receiving events.

Chapter 2
Overview
The SLEE maintains an implicit attachment count for each SBB entity. The a ttachment count of an SBB
entity is the total number of SBB entity to Activity Context attachments that the SBB entity and its descen-
dent SBB entities have.
Figure 3 illustrates attachment relations and counts graphically. In this graph, rectangles represent Activity
Contexts and ovals represent SBB entities. An SBB entity to Activity Context attachment is represented by
a non-directed edge between an SBB entity and an Activity Context. There is at most one edge between
each SBB entity and Activity Context pair. The attachment count of an SBB entity is the total number of
edges that connect the SBB entity and its descendents to Activity Contexts. The number in each oval is the
attachment count of the SBB entity.
AC1
Y1
(0)
X1
(6)
Z1
(4)
Y2
(2)
SLEE
AC2 AC3
Figure 3 SBB attachments

The attachment count of a parent SBB entity is the sum of the attachment counts of all its child SBB enti-
ties and the number of Activity Co ntexts that the parent SBB entity is directly attached to.
When an Activity Context’s Activity object ends, the SLEE detaches all SBB entities attached to the Activ-
ity Context (see Section 7.3.3). In a well-behaved system, Activity objects should end after a reasonable
finite amount of time. Eventually, the attachment count of the root SBB entity will reach zero.
The SLEE uses the attachment count of the root SBB entity to find out when the root SBB entity and its
descendents will no longer be receiving events (they must be attached to at least one Activity Context to
receive events). If the SLEE finds the root SBB entity’s attachment count to be zero after an invocation
(such as delivering an event), the SLEE reclaims the SBB entity tree by removing the root SBB entity. Re-
moving the root SBB entity initiates a cascading removal operation that also removes all the descendent
SBB entities (see Section 2.2.6).
Detach operations are transactional (see Chapter 9 for a more detailed discussion on transactions). The ef-
fects of the detach operation are only visible within the transaction until the transaction commits. If the
transaction does not commit, then the detach operation “did not” occur.
2.2.13 Activity Context reclamation and SBB entity tree removal example
In this example, there are two SBB entities in the SBB entity tree. There is a root SBB entity and the root
SBB entity has a single child SBB entity. The root SBB entity is not attached to any Activity Context and
the child SBB entity is attached to a single Activity Context.

Chapter 2
Overview
The following simplified4 example sequence illustrates how the SLEE and these SBB entities interact with
the Activity Context to reclaim the Activity Context after its underlying Activity object ends (see Section
7.2.4 for details) and to remove the SBB entity tree after it is no longer attached to any Activity Context .
1. The child SBB entity invokes a method on the underlying Activity object of the Activity Context
to end the Activity object (see Section 7.2.4). 5
2. The SLEE detaches all SBB entities from the Activity Context.6 When t he SLEE detaches the
child SBB entity from the Activity Context, the SLEE decrements the attachment count of the
child SBB entity from one to zero. It also decrements the attachment count of the ancestors of the
child SBB. In this case, the SLEE decrements the attachment count of the root SBB entity from
one to zero.
3. The SLEE reclaims the Activity Context 7 and removes the SBB entity tree by initiating a cascad-
ing removal of the root SBB entity as the root SBB attachment count is zero.
2.2.14 Activity Context Interface interface and object

An SBB entity interacts with an Activity Context through an Activity Context Interface object. The Activ-
ity Context Interface object provides an Activity Context with a visible Java API that can be invoked.
Through an Activity Context Interface object, an SBB can get access to the underlying Activity object of an
Activity Context.
All Activity Context Interface objects implement the generic ActivityContextInterface interface
and may optionally implement an extended SBB Activity Context Interface interface. The generic Activ-
ityContextInterface interface does not declare any shareable attributes. There are two kinds of Ac-
tivity Context Interface objects.
• Generic Activity Context Interface object.
A generic Activity Context Interface object implements the generic ActivityContextIn-
terface interface but does not implement an extended SBB Activity Context Interface interface.
It cannot be used to access attributes stored in an Activity Context.
• SBB Activity Context Interface object.
An SBB may define an SBB Activity Context Interface interface that extends the generic Activ-
ityContextInterface interface. The SBB Activity Context Interface interface defines the
SBB specific view of an Activity Context. An SBB Activity Context Interface object implements
an SBB Activity Context Interface interface. The SBB Activity Context Interface interface de-
clares the shareable attributes of the SBB (see Section 7.4). The SBB Activity Context Interface
interface provides a type-safe mechanism for accessing shareable attributes stored in Activity Con-
texts.
2.2.15 Profile, Profile Table, and Profile Specification

A Profile contains provisioned data. The schema of the Profile defines the attributes that may be provi-
sioned in the Profile. A Profile Table contains zero or more Profiles that conform to the same schema. A
Profile Specification defines the interfaces, classes, and deployment descriptor elements needed to define a
Profile schema and the interfaces used to provision and access a Profile that conforms to the Profile
schema. Zero or more Profile Tables can have the same Profile Specification.
The SLEE specification includes the following SLEE-defined Profile Specifications.
• A Resource Info Profile Specification.
This specifies the schema for all Resource Info Profile Tables and the interfaces used to provision
and access a Profile in one of these Profile Tables.
4
Not all steps are shown.
5
The SLEE moves the Activ ity Context to the Ending state.
6
After delivering an Activity End Event to the SBB entities attached to the Activity Context that can receive the Activity End Event.
7
The SLEE moves the Activity Context to the Invalid state.
Chapter 2
Overview
• A generic Address Profile Specification.

This specifies the schema for all generic Address Profile Tables and the interfaces used to provi-
sion and access a Profile in one of these generic Address Profile Tables.
In addition to these SLEE-defined Profile Specifications, SBB Developers can define custom Profile Speci-
fications.
2.2.16 Service
A Service is a deployment and management artifact. It specifies a child relation from the SLEE (as the logi-
cal parent of all root SBBs, see Figure 1) to a root SBB. Hence, it identifies the root SBB of the Service, the
default event delivery priority of the Service, and provides other information needed by the SLEE to instan-
tiate root SBB entities of the Service.
The SLEE will assign the default event delivery priority of the child relation to root SBB entities created by
the SLEE for this Service (see Figure 2).
To define a Service, the Administrator provides a Service deployment descriptor element that provides the
following:
• A globally unique name of the Service.
• A refere nce to a root SBB.
• An optional reference to a Resource Info Profile Table.
A Resource Info Profile Table contains provisioned data that the SLEE passes to resource adaptor
entities on behalf of the Services that reference this Profile Table.
• An optional reference to an Address Profile Table.
An Address Profile Table contains provisioned address data used by the SLEE to determine when
new root SBB entities of the Service are created.
Two Services may reference the same root SBB, but the Services may provide different event dispatch pri-
orities, reference different Resource Info Profile Tables and Address Profile Tables.
2.2.17 Service state

A Service can be in one of the following three operational states.
• Inactive.
The Service has been installed successfully and is ready to be activated. The Service is not run-
ning, i.e. root SBB entities of the Service’s root SBB will not be created to process events.
• Active.
The Service has been activated, i.e. it is running. The SLEE will create root SBB entities of the
Service’s root SBB to receive initial events and invoke SBB entities in the SBB entity trees of the
Service.
• Stopping.
The Service is being deactivated. However, some SBB entity trees of the Service still exist in the
SLEE and have not completed their processing. The SLEE is waiting for the SBB entities in these
SBB entity trees to complete processing so that they can be reclaimed. An SBB entity has com-
pleted processing and can be reclaimed when it and all of its child SBB entities are no longer at-
tached to any Activ ity Context (see Section 7.3.3).

Chapter 2
Overview
Inactive
activate Service
no more
Active outstanding
SBB entity trees
of the Service
deactivate Service
Stopping
Figure 4 Operational states of a Service

The following steps describe the life cycle of a Service:
• A Service enters the Inactive state when the Service is installed successfully into the SLEE.
• A Service enters the Active state from the Inactive state when the Service is activated. At this
point, the SLEE may start a Service Activity for the Service, and fire a Service Started Event on
this Activity, as described in Section 8.7.
• A Service enters the Stopping state from the Active state when the Service is deactivated.
At this point, the SLEE ends the Activity associated with the Service, if it exists (see Section
8.7.2), and fires an Activity End Event on this Activity. SBB entities belonging to the Service that
require clean-up when the Service is deactivated should listen to this event and terminate their
processing quickly but gracefully when this event is received. Optionally, after some SLEE im-
plementation determined time, the SLEE may also forcefully remove the outstanding SBB entity
trees of the Service.
• The SLEE moves a Service to the Inactive state from the Stopping state spontaneously when all
outstanding SBB entity trees of the Service complete their processing.
The operational state of a Service is persistent, i.e. the SLEE remembers the last state the Service is in. If
the SLEE is shut down and then restarted, the SLEE restores these Services to their previous operational
state.
2.2.18 Deployable unit

A deployable unit is a Jar file that can be installed in the SLEE. A deployable unit may contain Services,
SBB jar files, event jar files, Profile Specification jar files, resource adaptor type jar files, and resource
adaptor jar files. Each of these jar files contain the Java class files and the deployment descriptors of one or
more of these components.

Chapter 2
Overview
2.2.19 Management interface

The SLEE specification defines the external management interfaces that may be used by Administrators to
manage the SLEE and the Services running in the SLEE. These management interfaces define management
operations. Examples of management operations available through the SLEE’s management interfaces in-
clude:
• Start and stop the SLEE.
• Install and uninstall a deployable unit .
• Start and stop a Service.
• Create and delete a Profile Table.
• Add, remove, access and modify a Profile in a Profile Table.
• Register and deregister for alarm notifications.
• Register and deregister for trace notifications.
• Obtain and reset usage counters and statistics.
2.3 Roles
The SLEE architecture identifies the following roles:
• SBB Developer.
• Service Deployer.
• Administrator.
2.3.1 SBB Developer

The SBB Developer designs and implements SBBs. For each SBB, the SBB Developer defines the SBB’s
child relations, imple ments the SBB’s Java classes, and provides an SBB deployment descriptor. For each
child relation, the SBB Developer must provide the default event delivery priority and the child SBB. The
SBB Developer packages these files into an SBB jar file.
2.3.2 Service Deployer

The Service Deployer understands the operational environment. The Service Deployer should know which
Services have been or will be deployed into the SLEE and the external resources that are plugged into the
SLEE.
The Service Deployer creates a deployment descriptor element for each Service. In addition, the Service
specifies the default event delivery priority of the Service’s root SBB. The Service Deployer may also have
to modify the deployment descriptors of the SBBs that are directly or indirectly referenced by the root SBB
to adapt these SBBs to the operational environment. For example, the Service Deployer may have to iden-
tify and alias Activity Context attributes to resolve ambiguity and conflicts (see Section 7.8), add environ-
ment entries, add resource adaptor type, and resource adaptor entity bindings to SBB deployment descrip-
tors.
2.3.3 Administrator
The Administrator manages the SLEE and the applications running in the SLEE through the SLEE’s man-
agement interfaces. An Administrator may be a management client, such as a network management appli-
cation, network management console, or a person using a management client to manage the SLEE.

Chapter 3
Putting it Together
Chapter 3 Putting it Together

This chapter describes:
• How an SBB Developer creates SBBs and composes SBBs (see Section 3.1).
• How an SBB Developer creates custom event types (Section 3.2).
• How an SBB Developer creates Profile Specifications (see Section 3.3).
• How a Service Deployer defines a Service and customizes SBBs for deployment (see Section
3.4).
• How an Administrator manages Services and Profiles (see Section 3.5).
3.1 Create an SBB component

An SBB Developer creates an SBB from the following parts:
• Zero or more child SBBs, optional (see Section 3.1.2).
• An SBB local interface, optional (see Section 3.1.3).
• An SBB abstract class (see Section 3.1.4).
• An SBB Activity Context Interface interface, optional (see Section 3.1.5).
• An SBB deployment descriptor (see Section 3.1.8).
In addition, the SBB Developer may also define the components needed by the SBB. These components
include custom event types (see Section 3.2) and the provisioned data (see Section 3.3) used by the SBB.
3.1.1 Component identity of an SBB component

An SBB’s component identity uniquely identifies an SBB component. An SBB’s component identity does
not identify any particular SBB entity.
An SBB’s na me, vendor, and version, as defined by the sbb-name, sbb-vendor, and sbb-version
elements in the SBB’s deployment descriptor specify the component identity of an SBB.
The SbbID interface (see Section 14.7.5.2) defines the interface of a Java object that encapsulates an
SBB’s component identity. This Java object is also known as an SBB component identifier.
3.1.2 Building an SBB from child SBBs

The SBB Developer can develop and compose an SBB from zero or more child SBBs. The SBB Developer
should have a very good understanding of the child SBBs. The SBB Developer should understand each
SBB’s behavior and how each SBB interacts with other entities via local object invocations, events and
Activity Context attributes. These entities include other SBBs, resources, and the SLEE Facilities.
During this process, the SBB Developer:
• Must identify the child relations of the SBB and specify the default event delivery priority of the
relation.
• May alias Activity Context attributes.
Each SBB Activity Context Interface interface specifies the attributes that the SBB is willing to
share with other SBBs. By default, these attributes can be shared among SBB entities of the same
SBB component. However, they are not accessible by S BB entities of other SBBs to avoid unin-
tentional sharing resulting from two SBBs developed independently selecting the same attribute
name for two semantically distinct attributes. The SBB Developer identifies which attributes de-
clared in child SBB Activity Context Interface interfaces should be aliased. Attribute aliasing in-
structs the SLEE to make the aliased attributes behave logically as a single attribute. This logical

Chapter 3
Putting it Together
attribute can be updated through any of the aliased attributes’ set accessor methods. Changes to the
logical attribute are observable through any of the aliased attributes’ get accessor methods.
3.1.3 SBB local interface

The SBB Developer may optionally provide an SBB local interface. An SBB entity can invoke another
SBB entity synchronously through the SBB entity’s SBB local interface (see Chapter 5). The SBB local
interface must extend the javax.slee.SbbLocalObject interface. The SBB Developer declares the
following methods in the SBB local interface:
• Local interface methods.
The SBB Developer declares each method that may be invoked synchronously by other SBB enti-
ties.
This interface is optional. If the SBB Developer does not specify an SBB local interface, the SLEE supplies
the generic SbbLocalObject interface. This SbbLocalObject interface declares the remove
method used by an SBB entity to remove another SBB entity.
3.1.4 SBB abstract class

The SBB abstract class is mandatory. It contains the processing logic of the SBB. It implements the
javax.slee.Sbb interface. The SBB Developer provides the following methods:
• Event handler methods (see Section 8.4.2).
The SBB Developer implements an event handler method for each event type that may be received
by the SBB. Each event handler method contains the application logic for processing events of a
specific event type.
• Local interface methods (see Section 5.6).
The SBB Developer implements a method in the SBB abstract class for each method declared in
the SBB local interface.
• Life cycle callback methods (see Section 6.3).
An SBB object has a life cycle. The SLEE invokes one of these life cycle callback methods when
an SBB object transitions from one life cycle state to another life cycle state (see Section 6.2).
• An sbbExceptionThrown callback method (see Section 6.9.3).
The SLEE invokes this method after a SLEE originated invocation of a transactional method of
the SBB object returns by throwing a RuntimeException.
• An sbbRolledBack callback method (see Section 6.10).
The SLEE invokes this method after a transaction that was used to invoke a transactional method
of the SBB abstract class has been rolled back.
• Initial event selector methods (see Section 8.5.4).
The SBB Developer implements these optional methods to provide custom ways to determine if
an event is an initial event of the SBB.
The SBB Developer declares the following abstract methods. The SLEE implements these abstract methods
when the SBB is deployed.
• Fire event methods (see Section 8.4.1).
The SBB Developer declares an abstract method for each event type that may be fired by the SBB.
• CMP field get and set accessor methods (see Section 6.4.3).
The SBB Developer declares an abstract get and an abstract set method for each CMP field.
• Get child relation methods (see Section 6.8).
The SBB Developer declares a get child relation method for each child relation of the SBB. The
object returned by a get child relation method has methods to access the child SBB entities of the
relation and create additional SBB entities for this relation.

Chapter 3
Putting it Together
• Get Profile CMP methods (see Section 6.7).

The SBB Developer declares an abstract get Profile CMP method for each Profile CMP interface
(i.e. Profile Specification) accessed by the SBB.
• Get SBB Usage Parameter methods (see Section 0).
The SBB Developer may declare abstract get SBB Usage Parameter methods used by the SBB to
access objects that implement the SBB Usage Parameters interface of the SBB. Each of these ob-
jects represents a set of usage parameters that the SBB may manipulate (see Section 0).
• SBB Activity Context Interface narrow method (see Section 7.7.2).
The SBB Developer declares a method used to narrow an object that implements the generic Ac-
tivityContextInterface interface to an object that implements the SBB Activity Context
Interface interface of the SBB. This method is optional. The SBB Developer does not declare this
method if the SBB Developer does not define an SBB Activity Context Interface interface.
3.1.5 SBB Activity Context Interface interface

The SBB Activity Context Interface interface defines the SBB component specific view of an Activity
Context. The SBB Developer may provide an optional SBB Activity Context Interface interface. The SBB
uses this interface to access shared attributes stored in the Activity Context. The SBB Activity Context In-
terface interface must extend the generic ActivityContextInterface interface. It declares the
shareable state of the SBB as a set of attributes (see Section 7.4).
If the SBB Developer provides an SBB Activity Context Interface interface, the SBB Developer declares
the following abstract methods in the SBB Activity Context Interface interface:
• Get and set accessor methods.
The SBB Developer declares get and set accessor methods for each Activity Context attribute.
This interface is optional. If the SBB does not have any shareable attributes, the SBB Developer does not
have to provide an SBB Activity Context Interface interface.
If the SBB does not define an SBB Activity Context Interface interface, it interacts with Activity Contexts
through objects that implement the generic ActivityContextInterface interface that is defined by
the SLEE specification. The generic ActivityContextInterface interface defines a method that
provides access to the underlying Activity object of an Activity Context.
If the SBB Developer declares an SBB Activity Context Interface interface, the SBB Developer should also
declare an SBB Activity Context Interface interface narrow method to get access to objects that implement
the SBB Activity Context Interface interface.
3.1.6 SBB Usage Parameters interface

The SBB Developer may optionally provide an SBB Usage Parameters interface. The SBB declares the
names and types of the usage parameters relevant to this SBB in the SBB Usage Parameters interface by
declaring the methods used to manipulate these usage parameters. There are two types of usage p arameters :
counter-type and sample -type. An SBB can incre ment and decrement a counter-type usage parameter,
while a sample-type usage parameter accumulates data samples.
If the SBB Developer provides a SBB Usage Parameters interface, the SBB Developer declares the follo w-
ing abstract methods in the SBB Usage Parameters interface:
• Increment methods.
The SBB Developer declares increment methods to declare the presence of and to update counter-
type usage parameters. The SLEE derives the name of each usage p arameter from the name of
each increment method.
• Sample methods.
The SBB Developer declares sample method to declare the presence of and to add samples to
sample-type usage parameters . The SLEE derives the name of each usage p arameter from the
name of each sample method.

Chapter 3
Putting it Together
This interface is optional. If the SBB does not require any usage parameters, the SBB Developer does not
have to provide an SBB Usage Parameters interface.
If the SBB Developer declares an SBB Usage Parameters interface, the SBB Developer should also declare
(in the SBB abstract class) at least one of the get SBB Usage Parameter methods to get access to objects
that implement the SBB Usage Parameters interface.
3.1.7 Recommended SBB interfaces and classes naming convention

The SLEE specification recommends the following naming convention for the interfaces and classes of an
SBB component.
Class or interface Recommended Naming Convention
SBB abstract class <name>Sbb
SBB Activity Context Interface interface <name>SbbActivityContextInterface
SBB local interface <name>SbbLocalObject
3.1.8 SBB deployment descriptor

The SBB Developer identifies the SBB’s interfaces, classes, child relations, and Activity Context attribute
aliases in an SBB deployment descriptor.
An SBB deployment descriptor contains an sbb element. The sbb element contains the following sub-
elements:
• A description element.
This is an optional informational element.
• An sbb-name element, an sbb-vendor element, and an sbb-version ele ment.
These elements identify the SBB component.
• An sbb-alias element.
This element is optional. It assigns an alias to the SBB. Other elements in the same sbb element
use this alias to reference the SBB. It allows other elements in the enclosing sbb element to refer
to the SBB without specifying the SBB’s name, vendor and version. This element may be omitted
if the SBB is not referenced by other elements (such as get-child-relation-method ele-
ments) in the same sbb element. The scope of this alias is the enclo sing sbb element.
• Zero or more sbb-ref elements.
Each SBB referenced by the SBB of the enclosing sbb element must be identified by an sbb-
ref element. An sbb-ref element contains the following sub-elements.
o A description element.
o An sbb-name element, an sbb-vendor element, and an sbb-version e le ment.
These elements uniquely identify the referenced SBB component and must match exactly
the corresponding sbb-name, sbb-vendor, and sbb-version elements specified
in the referenced SBB’s sbb ele ment.
o An sbb-alias element.
This element assigns an alias to the referenced SBB. It allows other elements in the en-
closing sbb element to refer to the SBB without specifying the SBB’s name, vendor and
version. Other elements in the enclosing sbb element use this alias to reference the
aliased SBB. The scope of this alias is the enclosing sbb element.
• Zero or more profile-spec-ref elements.
Each Profile Specification used by the SBB must be identified by a profile-spec-ref e le-
ment. A profile-spec-ref element contains the following sub-elements.

Chapter 3
Putting it Together
o A profile-spec-name element, a profile-spec-vendor element, and a pro-
file-spec-version ele ment.
These elements uniquely identify the Profile Specification, and must match exactly the
corresponding profile-spec-name, profile-spec-vendor, and profile-
version elements specified in the referenced Profile Specification’s profile-spec
ele ment.
o A profile-spec-alias element.
This element is mandatory. It assigns an alias to the Profile Specification. It a llows other
elements in the enclosing sbb element to refer to the referenced Profile Specification
without specifying the Profile Specification’s name, vendor and version. Other elements
in the enclosing sbb element use this alias to reference the Profile Specification. The
scope of this alias is the enclosing sbb element.
• An sbb-classes element.
This element is mandatory. An sbb-classes element contains the following sub-elements:
o An sbb-abstract-class element.
It contains the following attribute and sub-elements:
§ A reentrant attribute.
This boolean attribute indicates whether the SBB component is re-entrant (see
Section 6.11), If this attribute is not specified, the default value is “False”.
§ A description element.
§ An sbb-abstract-class-name element.
This element identifies the class name of the SBB abstract class.
§ Zero or more cmp-field elements.
Each CMP field defined in the SBB abstract class must be identified by a cmp-
field element. Each cmp-field element contains the following sub-
elements:
• A cmp-field-name element.
This element identifies the name of the CMP field (see Section 6.4.3).
• An sbb-alias-ref element.
This optional element references an SBB by its sbb-alias that is
specified within the same sbb element. When this element is present,
only null and references to SBB entities of the SBB identified by this
element can be stored in the CMP field. If the Java type of the CMP
field is a SBB local interface (i.e., SbbLocalObject, or a type de-
rived from SbbLocalObject), then this element must be present.
§ Zero or more get-child-relation-method elements.
Each get child relation method declared in the SBB abstract class must be identi-
fied by a get-child-relation-method element. A get child relation
method declares a parent-child relation from the SBB to the SBB identified by
the enclosed sbb-alias-ref element. Each get-child-relation-
method element has the following sub-elements:
Chapter 3
Putting it Together
• An sbb-alias-ref element.
This element references an SBB by its sbb-alias that is specified
within the same sbb element.
• A get-child-relation-method-name element.
This element specifies the method name of the get child relation
method in the SBB abstract class. The SBB entity uses this method to
get an object that can be invoked to create child SBB entities and to
enumerate child SBB entities of this relation.
• A default-priority element.
This element is mandatory. A default-priority element speci-
fies the default event delivery priority of the child SBB relative to its
sibling SBBs (see Section 8.5.7).
§ Zero or more get-profile-cmp-method elements.
Each get Profile CMP method declared in the SBB abstract class must be identi-
fied by a get-profile-cmp-method element. Each get-profile-
cmp-method element has the following sub-elements:
• A profile-spec-alias-ref element.
This element refe rences a Profile Specification by its profile-
spec-alias that is specified in a profile-spec element within
the same sbb element.
• A get-profile-cmp-method-name element.
This element specifies the name of the method used to get an object
that implements a Profile CMP interface from a Profile identifier. The
Profile CMP interface is specified by the Profile Specification identi-
fied by the above profile-spec-alias-ref element.
o An sbb-local-interface element.
This ele ment is optional. If the SBB developer defines an SBB local interface, this ele-
ment identifies the SBB local interface. It contains the following sub-elements:
§ An sbb-local-interface-name element.
This element identifies the class name of the SBB local interface.
o An sbb-activity-context-interface element.
This element is optional. If the SBB developer defines an SBB Activity Context Interface
interface, this element identifies the SBB Activity Context Interface interface. It contains
the following sub-elements:
§ An sbb-activity-context-interface-name element.
This element identifies the class name of the SBB Activity Context Interface in-
terface.
o An sbb-usage-parameter-interface element.
This element is optional. If the SBB developer defines an SBB Usage Parameters inter-

Chapter 3
Putting it Together
face, this element identifies the SBB Usage Parameters interface. It contains the follo w-
ing sub-elements:
§ An sbb-usage-parameter-interface-name element.
This element identifies the class name of the SBB Usage Parameters interface.
• An address-profile-spec-alias-ref element.
This element is optional. If the SBB can be a root SBB, this element identifies the Address Profile
Specification of the SBB. This element references a Profile Specification by its profile-
spec-alias that is specified in a profile-spec-ref element in the same sbb element.
• Zero or more event elements.
Each event type that the SBB may receive or fire must have an event element (see Section 8.1).
An event element contains the following attributes and sub-elements:
o An initial-event attribute.
This attribute indicates if the event type is an initial event type (see Section 8.5.1).
o An event-direction attribute.
This attribute indicates if the SBB receives or fires the event type identified by the
event-type-ref element of the event element. The value of this attribute must be
“Receive”, “Fire”, or “FireAndReceive”. If initial-event is true, then event-
direction must be either “Receive” or “FireAndReceive”.
o A mask-on-attach attribute.
This attribute indicates whether events of the event type identified by the event-
type-ref element should be masked when an SBB entity attaches to an Activity Con-
text (see Section 7.4.1).
o An event-type-ref element.
This element references an event type. It contains the following elements:
§ An event-type-name element, an event-type-vendor element, and an
event-type-version element.
These elements uniquely identify an event type declared in an event-
definition element specified in another deployment descriptor. An event-
definition element declares an event type (see Section 8.3.1)
o An event-name element.
This element provides the SBB scoped name that the SBB uses to refer to the event type
identified by the event-type-ref element (see Section 8.1.10).
o Zero or more initial-event-select elements.
These elements are only meaningful if initial-event is true. They indicate which
convergence name variables should be selected (see Section 8.5.3). It has the following
attribute.
§ A variable attribute.
The value of this attribute can be one of “ActivityContext”, “AddressProfile”,
“Address”, “EventType”, or “Event”.
o An initial-event-selector-method-name element.
This element is optional and is meaningful only if initial-event is true. It identifies
an initial event selector method. The SLEE invokes this optional method to determine if

Chapter 3
Putting it Together
an event of the specified event type is an initial event if the SBB is a root SBB (see Sec-
tion 8.5.4).
o An event-resource-option element.
This element is optional. It provides additional event handling options that the SLEE
forwards to resource adaptor entities that emit events of the event type identified by the
event-type-ref element (see Section 8.3.2).
• Zero or more activity-context-attribute-alias elements.
These elements are optional. These elements and Activity Context attribute aliasing are described
in detail in Section 7.8. Each of these elements contains the following sub-elements:
o An attribute-alias-name element.
This element specifies an alias name. The alias name logically identifies the aliased logi-
cal attribute. This name is globally scoped. If two or more activity-context-
attribute-alias elements specify the same attribute-alias-name, all the
attributes specified by their sbb-activity-context-attribute elements are
aliased.
o One or more sbb-activity-context-attribute-name elements.
Each element identifies an attribute declared in the SBB Activity Context Interface inter-
face of the SBB that should be aliased. Each SBB Activity Context Interface attribute can
be aliased at most once, i.e. it is either not aliased or aliased through a single alias name.
• Zero or more env-entry elements.
These elements are optional. Each env-entry element binds an environment entry into the
JNDI component environment of the SBB (see Section 6.13). Each env-entry element contains
o An env-entry–name element.
This element specifies the location within the JNDI component environment to which the
environment entry value will be bound.
o An env-entry-value element.
This element specifies the value that will be bound to the location specified by the env-
entry–name element.
o An env-entry–type element.
This element specifies the type of the value specified by the environment env-entry
element.
• Zero or more resource-adaptor-type-binding elements.
These elements are optional. Each resource-adaptor-type-binding element declares a
resource adaptor type that the SBB depends on (see resource-adaptor-type-ref below).
It may optionally bind an object that implements the resource adaptor type defined Activity Con-
text Interface Factory interface into the JNDI component environment of the SBB (see Section
6.13.2). If necessary, it may also contain resource-adaptor-entity-binding sub-
elements that binds resource adaptor entities of the same resource adaptor type to be SBB. Each
resource-adaptor-type-binding element contains the following sub-elements:

Chapter 3
Putting it Together
o A resource-adaptor-type–ref element.
This element identifies the resource adaptor type that defines interface of the Activity
Context Interface Factory object. It contains the following sub-elements:
§ A resource-adaptor-type-name element, a resource-adaptor-
type-vendor element, and a resource-adaptor-type-version ele-
ment.
These elements uniquely identify the resource adaptor type, and must match e x-
actly the corresponding resource-adaptor-type-name, resource-
adaptor-type-vendor, and resource-adaptor-type-version
elements specified in the resource adaptor type’s resource-adaptor-type
ele ment.
o An activity–context-interface-factory-name element.
This optional element specifies the location within the JNDI component environment to
which the Activity Context Interface Factory object will be bound.
o Zero or more resource-adaptor-entity-binding elements.
Each resource-adaptor-entity-binding element binds an object that imple-
ments the resource adaptor interface of the resource adaptor type into the JNDI comp o-
nent environment of the SBB (see Section 6.13.3). Each re source-adaptor-
entity-binding element contains the following sub-elements:
§ A resource-adaptor-object–name element.
This element specifies the location within the JNDI component environment to
which the object that implements the resource adaptor interface will be bound.
§ A resource-adaptor-entity-link element.
This is an optional element. It identifies the resource adaptor entity that provides
the object that should be bound into the JNDI component environment of the
SBB. The identified resource adaptor entity must be an instance of a resource
adaptor whose resource adaptor type is specified by the resource-
adaptor-type-ref sub-element of the enclosing resource-adaptor-
type-binding element.
• Zero or more ejb-ref elements.
These elements are optional. Each ejb-ref element binds a reference to an Enterprise JavaBean
home into the JNDI component environment of the SBB. This allows the SBB to invoke Enter-
prise JavaBeans. Section 20.3 in the “Enterprise JavaBeans 2.0, Final Release” specification de-
scribes this element and how components get access to the referenced Enterprise JavaBean home.
This element contains the following sub-elements:
o An ejb-ref-name element.
o An ejb-ref-type element.
o A home element.
o A remote element.
o An ejb-link element.
This is an optional element.
3.1.9 SBB jar file

The SBB jar file is the standard format for packaging one or more SBBs. It must include the following:
Chapter 3
Putting it Together
• An SBB jar deployment descriptor.

o The SBB jar deployment descriptor is stored with the name META-INF/sbb-jar.xml
in the SBB jar file.
o The root element of the SBB jar deployment descriptor is an sbb-jar element. This
element has the following sub-elements.
§ One or more sbb elements.
Each of these elements is an SBB’s deployment descriptor as defined in Section
3.1.8.
• Class files of the SBBs specified by the sbb elements of the sbb-jar element.
o The SBB jar file must contain, either by inclusion or by reference, the class files of each
SBB.
o The SBB jar file must also contain, either by inclusion or by reference, the class files for
all the classes and interfaces that the SBBs’ classes and interfaces depend on, except
J2SE classes, SLEE classes, classes included in the SBB jar files of referenced SBBs of
the SBBs (see sbb-ref element), classes included in the event jar files of the event
types referenced by the SBBs (through event-type-ref elements), classes included
in the Profile Specification jar files of the Profile Specifications referenced by the SBBs
(through profile-spec-ref ele ments), classes included in the resource adaptor type
jar files referenced by the SBBs (through resource-adaptor-type-binding ele-
ments). This includes their superclasses and superinterfaces, dependent classes, and the
classes and interfaces used as method parameters, results, and exceptions.
A jar file contains a second file “by reference”, if the second file is named in the Class-
Path attribute in the Manifest file of the referencing jar file or is contained (either by in-
clusion or by reference) in another jar file that is named in the Class-Path attribute in the
Manifest file of the referencing jar file.
3.1.10 SBB jar file example

The following example illustrates an SBB jar file that contains a Foo SBB, and a Bar SBB. The Bar SBB is
a parent SBB of the Foo SBB. This example also shows the naming convention described in Section 3.1.7
and the deployment descriptors of the Foo SBB and Bar SBB.
The deployment descriptor for the example SBB jar file is as follows:
<sbb-jar>
<sbb>
<description> FooSbb … </description>
<sbb-name> Foo SBB </sbb-name>
<sbb-vendor> com.foobar </sbb-vendor>
<sbb-version> 1.0 </sbb-version>
…
<profile-spec-ref> … </profile-spec-ref>
…
<sbb-classes>
<sbb-abstract-class>
<description> … </description>
<sbb-abstract-class-name>
com.foobar.FooSbb
</sbb-abstract-class-name>
<cmp-field> … </cmp-field>
…
<get-profile-cmp-method>
…
</get-profile-cmp-method>
</sbb-abstract-class>

Chapter 3
Putting it Together
<sbb-local-interface>
<sbb-local-interface-name>
com.foobar.FooSbbLocalObject
</sbb-local-interface-name>
</sbb-local-interface>
<sbb-activity-context-interface>
<sbb-activity-context-interface-name>
com.foobar.FooSbbActivityContextInterface
</sbb-activity-context-interface-name>
</sbb-activity-context-interface>
<sbb-usage-parameter-interface>
<sbb-usage-parameter-interface-name>
com.foobar.FooSbbUsageParameter
</sbb-usage-parameter-interface-name>
</sbb-usage-parameter-interface>
</sbb-classes>
…
<event> … </event>
…
<activity-context-attribute-alias> … </activity-context-attribute-alias>
…
<env-entry> … </env-entry>
…
<resource-adaptor-type-binding>
…
<resource-adaptor-entity-binding>
…
</resource-adaptor-entity-binding>
…
</resource-adaptor-type-binding>
</sbb>
<sbb>
<description> BarSbb … </description>
<sbb-name> Bar SBB </sbb-name>
…
<sbb-ref>
<sbb-alias> FooSBB </sbb-alias>
</sbb-ref>
…
<sbb-classes>
…
com.foobar.BarSbb
…
<get-child-relation-method>
<sbb-alias-ref> FooSBB </sbb-alias-ref>
<get-child-relation-method-name>
…
</get-child-relation-method-name>
<default-priority> … </default-priority>
</get-child-relation-method >
…
</sbb-classes>
…
</sbb>
</sbb-jar>

Chapter 3
Putting it Together
The content of the SBB jar file is as follows:

META-INF/sbb-jar.xml
META-INF/MANIFEST.MF
…
com/foobar/BarSbb.class
com/foobar/FooSbb.class
com/foobar/FooSbbLocalObject.class
com/foobar/FooSbbActivityContextInterface.class
com/foobar/FooSbbUsageParameter.class
…
3.2 Custom event types

Custom event types are event types not defined by the SLEE specification or resource adaptor types
plugged into the SLEE. For each custom event type, the SBB Developer provides the follo wing parts:
• Custom event class.
The custom event class defines the methods and data of a custom event object.
• Custom event type.
A custom event type is defined by the custom event type’s name, vendor and version.
• An event definition deployment descriptor.
3.2.1 Event type deployment descriptor

Each custom event type must have an event definition deployment descriptor. An event definition deploy-
ment descriptor contains an event-definition element. Each event-definition element con-
tains the following sub-elements:
• An event-type-name element, an event-type-vendor element and an event-
version element.
These elements uniquely identify the event type.
• An event-class-name element.
This element identifies the Java class associated with the event type.
The SLEE and resource adaptor types also use event-definition elements to define the event types
they fire.
3.2.2 Event type packaging

The SBB Developer may distribute the event classes in either source form or compiled Java class files.
These files and the event definition deployment descriptor files may be distributed as separate files, or in
one or more jar files.
To ease distribution and deployable unit assembly, the SLEE specification recommends that the SBB De-
veloper distribute these files in an event jar file. The SLEE specification specifies the organization and con-
tent of an event jar file.
3.2.3 Event jar file

The event jar file is the standard format for packaging one or more event types. It must include the follo w-
ing:
• An event jar deployment descriptor.
o The event jar deployment descriptor is stored with the name META-INF/event-
jar.xml in the event jar file.

Chapter 3
Putting it Together
o The root element of the event jar deployment descriptor is an event-jar element. This
element contains the following sub-elements.
§ One or more event-definition elements.
Each of these elements is an event definition deployment descriptor as defined
in Section 3.2.1.
• Class files of the event types specified by the event-definition elements of the event-
jar element.
o The event jar file must contain, either by inclusion or by reference, the class file of the
event class.
o The event jar file must also contain, either by inclusion or by reference, the class files for
all the classes and interfaces that the event class depends on, except J2SE classes and
SLEE classes. This includes their superclasses and superinterfaces, dependent classes,
and the classes and interfaces used as method parameters, results, and exceptions.
3.2.4 Event jar file example

The following example illustrates an event jar file that contains two custom event types.
The deployment descriptor for the example event jar file is as follows:
<event-jar>
…
<event-definition>
…
<event-type-name> com.foobar.event.HelpRequestedEvent </event-type-name>
<event-type-vendor> com.foobar </event-type-vendor>
<event-type-version> 1.0a </event-type-version>
<event-class-name> com.foobar.event.HelpRequestedEvent </event-class-name>
</event-definition>
<event-definition>
…
<event-type-name> com.foobar.event.IVRCompletedEvent </event-type-name>
<event-type-version> 1.1 </event-type-version>
<event-class-name> com.foobar.event.IVRCompletedEvent </event-class-name>
</event-definition>
…
</event-jar>
The content of the event jar file is as follows:

META-INF/event-jar.xml
…
com/foobar/event/HelpRequestedEvent.class
com/foobar/event/IVRCompletedEvent.class
…
3.3 Profile Specification

For each type of provisioned data used by the SBB, the SBB Developer either provides a new Profile
Specification or identifies an existing Profile Specification that may be used by the SBB. For each Profile
Specification, the SBB Developer provides the following parts:
• A Profile CMP interface.
• An optional Profile Management interface.
• An optional Profile Management abstract class.
• A Profile Specification deployment descriptor.
Chapter 3
Putting it Together
3.3.1 Profile CMP interface

This interface defines the schema of a Profile Table created from this Profile Specification, i.e. it defines
the attributes of each Profile in the Profile Table. The SBB Developer declares the following methods in
the Profile CMP interface:
• Profile attribute get and s et accessor methods.
The SBB Developer declares each attribute using a pair of get and set accessor methods in this in-
terface.
3.3.2 Profile Management interface

The SBB Developer may provide an optional Profile Management interface. This interface declares the
methods that should be visible to a management client. The management client may be a network manage-
ment console, tool, or an Administrator.
If the SBB Developer provides a Profile Management interface, the SBB Developer declares the following
methods:
• Visible Profile attribute get and set accessor methods.
Each of these methods may be declared in the Profile Management interface or in a base interface
of the Profile Management interface. The Profile Management interface may extend the Profile
CMP interface to include all the accessor methods that are declared in the Profile CMP interface in
the Profile Management interface.
• Management methods.
These methods are methods declared in the Profile Management interface that are not also d e-
clared in the Profile CMP interface.
If the SBB Developer does not provide a Profile Management interface, then the SLEE makes all methods
declared in the Profile CMP interface visible.
3.3.3 Profile Management abstract class

The Profile Management abstract class implements management methods defined in the Profile Manage-
ment interface and the generic ProfileManagement interface. The ProfileManagement interface
defines the profile life cycle callback methods. The Profile Management abstract class also implements the
Profile CMP interface, but the SLEE implements the get and set accessor methods declared in the Profile
CMP interface when the Profile Specification is deployed.
If the SBB Developer provides a Profile Management abstract class, the SBB Developer implements the
following methods:
• Management methods declared by the SBB Developer in the Profile Management interface.
• Life cycle callback methods declared in the SLEE specification defined ProfileManagement
interface.
An instance of the Profile Management abstract class is known as a Profile Management object,
and has its own life cycle. The SLEE invokes one of these life cycle callback methods when a Pro-
file Management object transitions from one life cycle state to another life cycle state (see Section
10.9).
3.3.4 Profile Specification deployment descriptor

Each Profile Specification must have a Profile Specification deployment descriptor. A Profile Specification
deployment descriptor contains a profile-spec ele ment. Each profile-spec element contains the
following sub-elements:

Chapter 3
Putting it Together
• A profile-spec-name element, a profile-spec-vendor, and a profile-spec-

version element.
These elements uniquely identify a Profile Specification.
• A profile-classes element.
o A profile-cmp-interface-name element.
This element identifies the class name of the Profile CMP interface.
o A profile-management-interface-name ele ment.
This element is optional. If the Profile Specification defines a Profile Management inter-
face, this element identifies the Profile Management interface.
o A profile-management-abstract-class-name element.
This element is optional. If the Profile Specification defines a Profile Management ab-
stract class, this element identifies the Profile Management abstract class.
• Zero or more profile-index elements.
Each of these elements identifies an attribute in the Profile CMP interface and indicates that the
identified attribute should be indexed. This allows the SLEE to rapidly lookup a Profile within a
Profile Table created from this Profile Specification by the identified attribute. It contains the fol-
lowing attribute.
o A unique attribute.
This attribute is optional. This boolean attribute specifies whether a particular value of
this indexed attribute can only appear at most once in the Profile Table. If the Java type
of the indexed attribute is an array and the unique attribute is “True”, a particular value
stored in an array ele ment can also only appear once in the Profile Table, i.e. no two array
elements of the same indexed attribute stored in the same Profile or different Profiles
within the same Profile Table can have the same value. If not specified, the default value
is “False”. The null value is exempt from these uniqueness constraints and may appear
multiple times as a value of this attribute in multiple Profiles within the Profile Table.
• A profile-hint element.
This element is optional. It provides optimization hints for the Profile Specification. It contains the
following attribute.
o A single-profile attribute.
This attribute is optional. This boolean attribute specifies whether each Profile Table cre-
ated from this Profile Specification is expected to have only a single Profile. If not speci-
fied, the default value is “False”, i.e. each Profile Table can contain more than one Pro-
file.
3.3.5 Recommended Profile interfaces and classes naming convention

The SLEE specification recommends the following naming convention for the interfaces and classes of a
Profile Specification.
Class or interface Recommended Naming Convention
Profile CMP interface <name>ProfileCMP
Profile Management interface <name>ProfileManagement
Profile Management abstract class <name>ProfileManagementImpl

Chapter 3
Putting it Together
3.3.6 Profile Specification jar file

The Profile Specification jar file is the standard format for packaging one or more Profile Specifications. It
must include the following:
• A Profile Specification jar deployment descriptor.
o The Profile Specification jar deployment descriptor is stored with the name META-
INF/profile-spec-jar.xml in the Profile Specification jar file.
o The root element of the Profile Specification jar deployment descriptor is a profile-
spec-jar element. This element has the following sub-elements.
§ One or more profile-spec elements.
Each of these elements is a Profile Specification’s deployment descriptor as de-
fined in Section 3.3.4.
• Class files of the Profile Specifications specified by the profile-spec elements of the pro-
file-spec-jar element.
o The Profile Specification jar file must contain, either by inclusion or by reference, the
class files of each Profile Specification.
o The Profile Specification jar file must also contain, either by inclusion or by reference,
the class files for all the classes and interfaces that the Profile Specification’s classes and
interfaces depend on, except J2SE classes and SLEE classes. This includes their super-
classes and supe rinterfaces, dependent classes, and the classes and interfaces used as
method parameters, results, and exceptions.
3.3.7 Profile Specification jar file example

The following example illustrates a Profile Specification jar file that contains a BarAddressProfileSpec.
This example also shows the naming convention described in Section 3.3.5 and the deployment descriptor
of the BarAddressProfileSpec.
The deployment descriptor for the example Profile Specification jar file is as follows:
<profile-spec-jar>
<profile-spec>
…
<profile-spec-name> BarAddressProfileSpec </profile-spec-name>
<profile-spec-vendor> com.foobar </profile-spec-vendor>
<profile-spec-version> 3.1.1 </profile-spec-version>
<profile-classes>
<profile-cmp-interface-name>
com.foobar.BarAddressProfileCMP
</profile-cmp-interface-name>
<profile-management-interface-name>
com.foobar.BarAddressProfileManagement
</profile-management-interface-name>
<profile-management-abstract-class-name>
com.foobar.BarAddressProfileManagementImpl
</profile-management-abstract-class-name>
</profile-classes>
…
</profile-spec>
</profile-spec-jar>
The content of the Profile Specification jar file is as follows:

META-INF/profile-spec-jar.xml
…
com/foobar/BarAddressProfileCMP.class

Chapter 3
Putting it Together
com/foobar/BarAddressProfileManagement.class
com/foobar/BarAddressProfileManagementImpl.class
…
3.4 Create a Service

The Service Deployer creates a Service by:
• Defining the Service.
• Customizing the SBBs of the Service to the target operational environment.
• Packaging the Service in a deployable unit.
3.4.1 Service deployment descriptor

The Service Deployer specifies the following aspects of the Service in the Se rvice deployment descriptor.
A Service deployment descriptor contains a service element. The service element contains the fol-
lowing sub-elements:
• A service-name element, a service-vendor element, and a service-version e le-
ment.
These elements identify the Service.
• A root-sbb element.
This element identifies the root SBB of the Service. A root-sbb element contains the following
sub-elements.
o An sbb-name element, an sbb-vendor element, and an sbb-version e le ment.
These elements uniquely identify the root SBB.
• A default-priority element.
This element specifies the default event delivery priority for the child relation from the SLEE to
root SBB.
• An address-profile-table element.
This element is optional. This Profile Table contains provisioned addresses that may cause new
root SBB entities of the Service to be instantiated. This element specifies the Address Profile Ta-
ble of the Service. The Profile Specification of this Profile Table must be the same as the Profile
Specification specified by the address-profile-spec-alias-ref of the root SBB.
• A resource-info-profile-table element.
This element is optional. This table contains provisioned data that should be passed to resource
adaptor entities when the Service is in running. This element specifies the Resource Info Profile
Table of the Service. The Profile Specification of this Profile Table must be the SLEE specifica-
tion defined Resource Info Profile Specification.
3.4.2 Component identity of a Service

The component identity of Service uniquely identifies a Se rvice. A Service’s name, vendor, and version (as
defined by the service-name, service-vendor, and service-version deployment descriptor
elements) determine the component identity of a Service.
The ServiceID interface (see Section 14.7.5.2) defines the interface of a Java object that encapsulates a
Service’s component identity. This Java object is also known as a Service component identifier.

Chapter 3
Putting it Together
3.4.3 Customizing the Service to the operational environment

The Service Deployer can also customize the root SBBs and their child SBBs to the target operational envi-
ronment. The Service Deployer should have a good understanding of the target operational environment.
The target operational environment includes the available resource adaptor types, resource adaptors, re-
source adaptor entities, other SBBs and Services that have already been installed.
The Service Deployer can adapt and customize an SBB to the target operational environment by modifying
deployment descriptor elements of the SBB. The Service Deployer may have to disassemble SBB jar files
to mo dify these deployment descriptor elements or the SLEE may provide tools to modify these deploy-
ment descriptor elements.
The Service Deployer can add and modify the following SBB deployment descriptor elements:
• attribute-context-attribute-alias elements.
Two independent sets of SBBs developed independently may choose the same alias name for two
different logical attributes. The Service Deployer can resolve Activity Context attribute alias name
conflicts by modifying attribute-alias-name ele ments.
• env-entry elements.
• resource-adaptor-type-binding elements.
• resource-adaptor-entity-binding elements.
• ejb-ref elements.
The Service Deployer should avoid modifying other SBB deployment descriptor elements.
3.4.4 Packaging the Service for deployment

The SBB Developer distributes one or more Service deployment descriptors in a Service XML deployment
descriptor file. This file contains a single service-xml element. The service-xml element contains
• One or more service elements.
Each of these elements is a Service’s deployment descriptor as defined in Section 3.4.1.
An example Service XML deployment descriptor file may be as follows:
<service-xml>
…
<service>
<description>
…
</description>
<service-name> FooService </service-name>
<service-vendor> com.foobar </service-vendor>
<service-version> 1.0 </service-version>
<root-sbb>
</root-sbb>
<default-priority> … </default-priority>
<address-profile-table> … </address-profile-table>
<resource-info-profile-table> … </resource-info-profile-table>
…
</service>
…
</service-xml>

Chapter 3
Putting it Together
3.4.5 Deploying components

Before event types, Profile Specifications, SBBs and Services can be deployed or installed into a SLEE, the
Service Deployer must create a deployable unit that contains the components that are to be deployed.
A deployable unit is a jar file. This jar file contains a deployable unit deployment descriptor, the constituent
jar files and Service XML files of the deployable unit. The deployable unit deployment descriptor is stored
with the name META-INF/deployable-unit.xml in the deployable unit jar file.
A deployable unit deployment descriptor contains a deployable-unit ele ment. The deployable-
unit element contains the following sub-elements:
• One or more jar elements.
Each jar element contains the name of a constituent jar file included in the deployable unit jar
file. This name is relative to the root of the deployable unit jar file. The constituent jar file may be
an SBB jar file, Profile Specification jar file, an event jar file, a resource adaptor type jar file. The
type of the constituent jar file is determined from the constituent jar file.
• Zero or more service-xml deployment descriptor elements.
Each of these elements specifies the name of a Service XML deployment descriptor file. This
name is relative to the root of the deployable unit jar file.
Event types and Profile Specifications that may potentially be referenced by multiple deployable units
should be packaged in independent deployable units. If these components are packaged in a deployable unit
that contains a Service, then the Service cannot be uninstalled independently without uninstalling those
components that other deployable units may depend on.
3.4.6 Deployable unit jar file example

The following example illustrates a deployable unit jar file.
The deployment descriptor for the example deployable unit jar file is as follows:
<deployable-unit>
…
<jar> FooSBB.jar </jar>
<jar> BarSBB.jar </jar>
<jar> SomeProfileSpec.jar </jar>
<jar> BarAddressProfileSpec.jar </jar>
<jar> SomeCustomEvent.jar </jar>
…
<service-xml> FooService.xml </service-xml>
…
</deployable-unit>
The content of the deployable unit jar file is as follows:
META-INF/deployable-unit.xml
…
FooSBB.jar
BarSBB.jar
SomeProfileSpec.jar
BarAddressProfileSpec.jar
SomeCustomEvent.jar
FooService.xml
…
3.5 Administer Services and Profiles

The Administrator can perform the following management operations through the management interfaces
of the SLEE:
Chapter 3
Putting it Together
• Operations on deployable units.

o Install and uninstall a deployable unit.
o Find out what components are in an installed deployable unit.
• Operations on Services.
o Activate and deactivate a Service.
o Get the life cycle state of a Service.
o List the Services in a particular life cycle state.
o Get and reset the usage parameters of SBBs in a Service.
o Get and set the trace filter level for a Service.
• Operations on Profiles.
o Create Profile Tables from Profile Specifications.
o Add and remove Profiles from Profile Tables.
o Read and modify Profiles.
Typically, the Administrator performs the following sequence of management operations on a Service:
• Install the deployable unit jar file provided by the Service Deployer into the SLEE.
This deployable unit includes the Service deployment descriptor and the SBB jar files of the SBBs
of the Service.
• Create the Profile Tables required by the Service.
If the Service specifies an Address Profile Table, the specified Address Profile Table must be cre-
ated before the Service can be activated. If the Service specifies a Resource Info Profile Table, the
specified Resource Info Profile Table must be created before the Service can be activated.
• Populate Profile Tables with Profiles.
The Administrator may populate Profile Tables that contain common configuration data for the
SBBs of the Service.
• Activate the Service.
At this point, the SLEE may create new root SBB entities for the Service to process events.
• Add, remove and modify Profiles.
Profiles typically contain provisioned data that represent subscribers. For example, Address Pro-
files may be added or removed as subscribers are added or removed. A subscriber’s data ma y be
stored in one or more Profiles in one or more Profile Tables. The Administrator adds, removes and
modifies these Profiles as subscribers are added, removed, or when their subscriber data changes.
• Deactivate the Service.
At this point, no new root SBB entities are created for the service.
• Uninstall the deployable unit.
After the SLEE uninstalls the deployable unit, it loses all knowledge of the Services in the deploy-
able unit.

Chapter 4
Addresses
Chapter 4 Addresses
An address is a unique identifier for an entity in a network or the SLEE. A common address today is a tele-
phone number or a URI address.
4.1 Address objects

The SLEE uses an Address object to represent an address. An Address object is an instance of the Ad-
dress class. The SLEE APIs pass Address objects wherever a method returns one or more addresses or
requires one or more addresses as input arguments. The Address clas s allows resources to use the same
Address object for different resources and/or resource adapters.
The public interface of the Address class is as follows.
package javax.slee;
public class Address {

public Address(AddressPlan addressPlan,
String addressString) { … }
public Address(AddressPlan addressPlan,
String addressString,
AddressPresentation addressPresentation,
AddressScreening addressScreening,
String subAddressString,
String addressName) { … }
public AddressPlan getAddressPlan() { … }
public String getAddressString(){ … }
public AddressPresentation getAddressPresentation() { … }
public AddressScreening getAddressScreening() { … }
public String getSubAddressString() { … }
public String getAddressName() { … }
public String toString() { … }
public int hashCode() { … }
public boolean equals(Object o) { … }
}
• The addressPlan attribute.

It specifies the address plan of the address. The address plan determines the format of the address
string and how it should be interpreted. It is mandatory in all addresses.
• The addressString attribute.
It specifies the address string of the address. The address string is the unique address value that
identifies an end user in a specific type of network. It is mandatory in all addresses.
• The addressPresentation attribute.
It specifies the address presentation of the address. The address presentation is optional and the
value of this attribute is null when an address presentation is not provided.
• The addressScreening attribute.
It specifies the address screening of the address. The address screening is optional and the value of
this attribute is null when an address screening is not provided.
• The subAddressString attribute.
It specifies the sub-address of the address. Some protocols allow sub -addressing (e.g. extensions)
within an address. The sub-address is optional and the value of this attribute is null when a sub-
address is not provided.
• The addressName attribute.
It specifies the address name of the address. Some systems allow a personal name to be displayed
instead of the actual address string. The address name is optional and the value of this attribute is
null when an address name is not provided.

Chapter 4
Addresses
The following rules apply to Address objects.
• An Address object is immutable. Once it has been created, its contents cannot be changed.
• An Address object must al least have both a valid address plan and a valid address string. The
address string must be of the format defined by the address plan. Either public constructor can be
used to initialize an Address object with a valid address plan and address string.
4.2 AddressPlan objects

The AddressPlan class defines an enumerated type for address plans.
The address plan of an address determines the format and structure of the address string specified in the
addressString attribute of the Address object. The SLEE supports the JAIN SPA Common specifi-
cation address plans and the following additional address plans, H323, Globaltitle, Subsystem Number
(SSN), E164_Mobile, SLEE Profile Tables and SLEE Profiles.
The public interface of the AddressPlan class is as follows.
package javax.slee;
public class AddressPlan {

// singletons
public static AddressPlan NOT_PRESENT …;
public static AddressPlan UNDEFINED …;
public static AddressPlan IP …;
public static AddressPlan MULTICAST …;
public static AddressPlan UNICAST …;
public static AddressPlan E164 …;
public static AddressPlan AESA …;
public static AddressPlan URI …;
public static AddressPlan NSAP …;
public static AddressPlan SMTP …;
public static AddressPlan E164_MOBILE …;
public static AddressPlan X400 …;
public static AddressPlan SIP …;
public static AddressPlan H323 …;
public static AddressPlan GT …;
public static AddressPlan SSN …;
public static AddressPlan SLEE_PROFILE_TABLE …;
public static AddressPlan SLEE_PROFILE …;
// integer representation
public static int ADDRESS_PLAN_NOT_PRESENT …;
public static int ADDRESS_PLAN_UNDEFINED …;
public static int ADDRESS_PLAN_IP …;
public static int ADDRESS_PLAN_MULTICAST …;
public static int ADDRESS_PLAN_UNICAST …;
public static int ADDRESS_PLAN_E164 …;
public static int ADDRESS_PLAN_AESA …;
public static int ADDRESS_PLAN_URI …;
public static int ADDRESS_PLAN_NSAP …;
public static int ADDRESS_PLAN_SMTP …;
public static int ADDRESS_PLAN_E164_MOBILE …;
public static int ADDRESS_PLAN_X400 …;
public static int ADDRESS_PLAN_SIP …;
public static int ADDRESS_PLAN_H323 …;
public static int ADDRESS_PLAN_GT …;
public static int ADDRESS_PLAN_SSN …;
public static int ADDRESS_PLAN_SLEE_PROFILE_TABLE …;
public static int ADDRESS_PLAN_SLEE_PROFILE …;
public boolean isNotPresent() { … }

public boolean isUndefined() { … }
public boolean isIP() { … }
public boolean isMulticast() { … }
public boolean isUnicast() { … }
public boolean isE164() { … }

Chapter 4
Addresses
public boolean isAESA() { … }
public boolean isURI() { … }
public boolean isNSAP() { … }
public boolean isSMTP() { … }
public boolean isE164Mobile() { … }
public boolean isX400() { … }
public boolean isSIP() { … }
public boolean isH323() { … }
public boolean isGT() { … }
public boolean isSSN() { … }
public boolean isSleeProfileTable() { … }
public boolean isSleeProfile() { … }
public static AddressPlan fromInt(int plan)

throws IllegalArgumentException { … }
public int toInt() { … }
}
• A singleton instance of each enumerated value is guaranteed (via an implementation of the read-
Resolve method, see java.io.Serializable for more details), so that equality tests using
== are always evaluated correctly. For convenience, an integer representation of AddressPlan
objects is also available.
• Each of the is<Plan> methods determines if this AddressPlan object represents the
<PLAN> of the address, and is equivalent to (this == <PLAN>). For e xample, the isSIP
method determines if this AddressPlan object represents the SIP plan of the address and is
equivalent to (this == SIP).
• The fromInt and toInt methods allow conversion between the AddressPlan object form
and numeric form.
• The fromInt method throws a java.lang.IllegalArgumentException if the plan
argument is not one of the integer address plan representations.
4.3 Address string

The Java type of the addressString attribute is java.lang.String. It contains an address string.
An address string is a string of characters or decimal digits segmented into groups in order to identify spe-
cific elements used for identification, routing and charging capabilities. Each address plan defines the fo r-
mat of address strings that are valid for the address plan. This attribute cannot contain wildcards. Examples
of valid address strings for three address plans follows:
• An address with an URI address plan specifies a protocol, a domain and an optional path informa-
tion and has the format “protocol://domain[/path]”, e.g. “http://www.foobar.com/index.html”.
• An address with an address plan of type SIP has an address string in the format of
“sip:[name][@domain]”, e.g. “sip:[email protected]”.
• The address string of an address with an address plan of type E164 should be an international tele-
phone number without the international access code, including the country code and excluding the
leading zero of the area code, e.g., “1650999999” for a US based number.
4.4 AddressPresentation objects

The AddressPresentation class defines an enumerated type for address presentations. The address
presentation of an address defines whether an address can be presented to other call parties. The user appli-
cation determines whether the address is to be presented to other end-users.
The public interface of the AddressPresentation class is as follows.
package javax.slee;

Chapter 4
Addresses
public class AddressPresentation {

// singletons
public static AddressPresentation ALLOWED …;
public static AddressPresentation RESTRICTED …;
public static AddressPresentation UNDEFINED …;
public static AddressPresentation ADDRESS_NOT_AVAILABLE …;
public static int ADDRESS_PRESENTATION_ALLOWED …;
public static int ADDRESS_PRESENTATION_RESTRICTED …;
public static int ADDRESS_PRESENTATION_UNDEFINED …;
public static int ADDRESS_PRESENTATION_ADDRESS_NOT_AVAILABLE …;
public boolean isAddressNotAvailable() { … }

public boolean isRestricted() { … }
public boolean isAllowed() { … }
public static AddressPresentation fromInt(int plan)

public int toInt() { … } …
}
== are always evaluated correctly. For convenience, an integer representation of AddressPre-
sentation objects is also available.
• Each of the is<Presentation> methods determines if this AddressPresentation object
represents the <PRESENTATION> of the address, and is equivalent to (this ==
<PRESENTATION>). For example, the isAllowed method determines if this AddressPre-
sentation object represents the Allowed presentation of the address and is equivalent to
(this == ALLOWED).
• The fromInt and toInt methods allow conversion between the AddressPresentation
object form and numeric form.
• The fromInt method throws a java.lang.IllegalArgumentException if the pres-
entation argument is not one of the integer address presentation representations.
4.5 AddressScreening objects

The AddressScreening class defines an enumerated type for the address screenings. The address
screening of an address defines whether an address has been screened by a user application. The user can
optionally choose one of these constants depending on whether they have screened their address and the
outcome they received. The address can be screened either by the network or a user or the address screen-
ing may be undefined.
The public interface of the AddressScreening class is as follows.
package javax.slee;
public class AddressScreening {
// singletons
public static AddressScreening NETWORK …;
public static AddressScreening UNDEFINED …;
public static AddressScreening USER_NOT_VERIFIED …;
public static AddressScreening USER_VERIFIED_PASSED …;
public static AddressScreening USER_VERIFIED_FAILED …;

Chapter 4
Addresses
public static int ADDRESS_SCREENING_NETWORK …;
public static int ADDRESS_SCREENING_UNDEFINED …;
public static int ADDRESS_SCREENING_USER_NOT_VERIFIED …;
public static int ADDRESS_SCREENING_USER_VERIFIED_PASSED …;
public static int ADDRESS_SCREENING_USER_VERIFIED_FAILED …;
public boolean isNetwork() { … }

public boolean isUserNotVerified() { … }
public boolean isUserVerifiedPassed() { … }
public boolean isUserVerifiedFailed() { … }
public static AddressScreening fromInt(int plan)

}
== are always evaluated correctly. For convenience, an integer representation of AddressS-
creening objects is also available.
• Each of the is<Screening> methods determines if this AddressScreening object repre-
sents the <SCREENING> of the address, and is equivalent to (this == <SCREENING>). For
example, the isNetwork method determines if this AddressScreening object represents the
Network screening of the address and is equivalent to (this == NETWORK).
• The fromInt and toInt methods allow conversion between the AddressScreening object
form and numeric form.
• The fromInt method throws a java.lang.IllegalArgumentException if the
screening argument is not one of the integer address presentation representations.
4.6 Address example

An example email address that can be presented to the user and has been screened by the network has the
following attribute values:
• addressPlan = AddressPlan.SMTP
• addressString = ”[email protected]”
• addressScreening = AddressScreening.NETWORK
• addressPresentation = AddressPresentation.ALLOWED
• addressName = ”Alice”

Chapter 5
SBB Local Interface
Chapter 5 SBB Local Interface

An SBB entity can invoke a target SBB entity in a synchronous manner through the SBB local interface of
the target SBB. This interface is known as the SBB local interface because the SBB object that represents
the caller and the SBB object that represents the callee must be collocated in the same JVM. In order to be
invoked synchronously, an SBB must declare an SBB local interface. The SBB local interface declares the
methods of the SBB that may be invoked synchronously. An SBB local object is an instance of a SLEE
implemented class that implements an SBB local interface.
5.1 How to obtain an SBB local object

An SBB can obtain an SBB local object that represents an SBB entity via the following mechanisms:
• Receive the SBB local object as the result of invoking the create method on a ChildRela-
tion object.
• Receive the SBB local object as the result of invoking the getSbbLocalObject method on an
SbbContext object.
• Receive the SBB local object as a result of a method call on an SBB local object. The callee may
receive the SBB local object through one of its input arguments. The caller may receive the SBB
local object through the return argument.
• Retrieve an SBB local object from a CMP field (see Section 6.4.3).
• Receive a ChildRelation object that implements the java.util.Collection interface.
This ChildRelation object and its Iterator objects provide access to SBB local objects.
5.2 What can be done with an SBB local object

An SBB object holding a reference to an SBB local object may do any of the following:
• Test if the SBB local object represents the same SBB entity as another SBB local object.
• Remove the SBB entity (and the SBB entity’s descendents) represented by the SBB local object.
• Set and get the event delivery priority of the SBB entity represented by the SBB local object.
• Invoke an SBB Developer defined method of the SBB local object.
• Pass the SBB local object in an input or return argument of a local method call.
• Store the SBB local object into a CMP field.
5.3 A typical scenario

In a typical scenario, an SBB object that represents a parent SBB entity creates a child SBB entity by in-
voking the create method on one of its ChildRelation objects. The create method returns an ob-
ject that implements the SBB local interface of the child SBB entity. This returned object is an SBB local
object that represents the newly created child SBB entity. Zero or more SBB local objects may represent
the same SBB entity.
When the parent or another SBB invokes an SBB Developer defined method on the SBB local object, the
SBB local object delegates the method invocation to a local SBB object that represents the target SBB en-
tity. The SLEE is responsible for providing a suitable local SBB object to receive this method invocation. If
a suitable local SBB object does not exist, the SLEE may have to create a new SBB object or obtain an
existing SBB object in the Pooled state, and assign the SBB object to the target SBB entity.
When the SBB entity represented by the SBB local object no longer exists (because it has been deleted), a
method invocation on the SBB local object will:
• Mark the current transaction for rollback, and

Chapter 5
SBB Local Interface
• Return by throwing the javax.slee.TransactionRolledbackLocalException.
5.4 Pass-by-reference semantics

The arguments of the methods of the SBB local interface are passed by reference. An SBB that defines an
SBB local interface must be coded to assume that the caller and the callee may potentially reference the
same Java object that is passed directly or indirectly as an argument or result. In designing an SBB that
makes use of the local programming model offered by SBB local interfaces, the SBB Developer must be
aware of the potential multiple references to the same objects passed through the SBB local interface. In
particular, the SBB Developer must be careful that one SBB object does not reference Java objects that are
intended to be the private state of another SBB object. The caller and callee SBB object may be pro-
grammed to rely on pass-by-reference semantics. For example, a caller may have a large document that it
wants to pass to the callee to modify (and the callee further passes on). In the local programming model, the
sharing of state is possible. On the other hand, when the callee wants to return a data structure to the caller
but the caller does not want the callee to modify it, the caller explic itly copies the data structure before
passing it.
5.5 The SbbLocalObject interface

This interface is the base interface of all SBB local interfaces. All SBB local interfaces e xtend the
SbbLocalObject interface. If an SBB does not define an SBB specific local interface, then the SBB’s
local interface is SbbLocalObject.
The SLEE provides the implementation of the methods defined in the SbbLocalObject interface.
The SbbLocalObject interface is as follows:
package javax.slee;
public interface SbbLocalObject {

public boolean isIdentical(SbbLocalObject obj)
throws TransactionRequiredLocalException,
SLEEException;
public void setSbbPriority(byte priority)
throws TransactionRolledbackLocalException,
TransactionRequiredLocalException,
SLEEException;
public byte getSbbPriority()
SLEEException;
public void remove()
SLEEException;
}
5.5.1 SbbLocalObject interface isIdentical method

This method determines if two SBB local objects represent the same SBB entity.
• The SLEE specification does not specify “object equality” (i.e. use of the == operator) for SBB
local object references. The result of comparing two SBB local object references using the Java
programming language Object.equals method is unspecified. Performing the Object.ha-
shCode method on two SBB local objects that represent a single SBB entity is not guaranteed to
yield the same result. Therefore, the isIdentical method should be used to determine if two
SBB local objects represent the same SBB entity.
• This method is a mandatory transactional method (see Section 9.6.1). It throws a javax.sl-
ee.TransactionRequiredLocalException if it is invoked without a valid transaction
context.

Chapter 5
SBB Local Interface
• This method throws a javax.slee.SLEEException if the method failed due to a SLEE

level or system level failure.
5.5.2 SbbLocalObject interface setSbbPriority method

An SBB object invokes the setSbbPriority method on an SBB local object that represents a second
SBB entity to set the event delivery priority of the second SBB entity relative to the second SBB’s siblings
• The priority argument specifies the new priority. The priority has the range of –128 to 127 in-
clusive.
• All SBB local objects that represent an SBB entity that does not exist are invalid. An attempted
method invocation on an invalid SBB local object marks the current transaction for rollback and
throws a javax.slee.TransactionRolledbackLocalException (a subclass of
javax.slee.SLEEException).
context.
• This method may also throw the javax.slee.SLEEException if the method failed due to a
SLEE level or system level failure. If the caller of this method receives this exception, the caller
does not know, in general, whether the priority was set or not. The caller also does not know if the
transaction has been marked for rollback. However, the caller may determine the priority by using
getSbbPriority and determine the transaction status by using the getRollbackOnly
method (see Section 6.10.3).
5.5.3 SbbLocalObject interface getSbbPriority method

An SBB object invokes the getSbbPriority method on an SBB local object that represents the a sec-
ond SBB entity to get the event delivery priority of the second SBB entity relative to the second SBB en-
tity’s siblings (see Section 8.5.7).
• The return value is the second SBB entity’s priority. The priority has the range of –128 to 127 in-
clusive.
context.
• This method may also throw the javax.slee.SLEEException if the method failed due to a
SLEE level or system level failure.
5.5.4 SbbLocalObject interface remove method

An SBB object invokes the remove method on an SBB local object that represents the second SBB entity
to initiate a cascading removal of the second SBB entity and the second SBB entity’s descendents (see Sec-
tion 2.2.6).
• When the SLEE performs a cascading removal of an SBB entity sub-tree, it performs a pre-order
traversal of the sub-tree to delete the SBB entities in the sub-tree. It deletes the parent SBB entity
before it deletes the child SBB entities. The SLEE does not specify the order in which sibling SBB
entities are deleted. When the SLEE deletes an SBB entity, it does the follo wing:

Chapter 5
SBB Local Interface
o It detaches the SBB entity from all Activity Contexts.

o It invokes the appropriate life cycle methods (see Section 6.3) of an SBB object that
caches the SBB entity’s state.
o It removes the SBB entity from the ChildRelation object that the SBB entity be-
longs to.
o It removes the persistent representation of the SBB entity.
The SLEE performs the above operations of a cascading removal in the same transaction that the
remove method was invoked in. If the transaction commits, the result of the above operations be-
come permanent. Otherwise, if the transaction does not commit, the changes are discarded.
context.
• This method may also throw a javax.slee.SLEEException if the method failed due to a
does not know, in general, whether the entity object was removed or not. The caller also does not
know if the transaction has been marked for rollback. Ho wever, the caller may determine the
transaction status by using the getRollbackOnly method (see Section 6.10.3).
Logically, the SLEE also invokes this method to remove an SBB entity tree. The SLEE invokes this
method on the root SBB entity of the SBB entity tree after the attachment count of the root SBB entity dec-
rements to zero. This method initiates a cascading removal of the SBB entity tree. If this method returns by
throwing a RuntimeException, the SLEE should log this condition. Furthermore, it may forcefully
delete the persistent state of the SBB entities in the SBB entity tree, or provide some other mechanism for
the Administrator to manually delete the persistent state of these SBB entities. In either case, the SLEE
should behave as if the SBB entity tree is successfully re moved, i.e. the root SBB entity of the SBB entity
tree is no longer a child SBB entity of the SLEE and it will no longer have any effect on event routing.
5.6 The SBB local interface

An SBB may define SBB specific local interface methods in an SBB specific local interface.
• The SBB specific local interface must be public and must extend, either directly or indirectly,
the SbbLocalObject interface.
• All SBBs have an SBB local interface. If the SBB Developer does not provide an SBB local inter-
face for an SBB, then the SBB local interface of the SBB is the generic SbbLocalObject inter-
face.
• The names of the SBB specific local interface methods must not begin with “sbb” or “ejb”.
• The SLEE provides the implementation of the methods defined in the SBB local interface. More
precisely, the SLEE provides a concrete class that implements each SBB local interface. An SBB
local object is an instance of this class. The SLEE provided implementations of these methods
delegate invocations on an SBB local object that represents an SBB entity to an SBB object that
represents the SBB entity (if the SBB entity has not been removed).
• The SBB Developer provides the implementation of SBB Developer defined local interface meth-
ods declared in the SBB specific extension of the SbbLocalObject interface in the SBB ab-

Chapter 5
SBB Local Interface
stract class. For each method defined by the SBB Developer, there must be a matching method in
the SBB abstract class. The matching method must have:
o The same name.
o The same number of arguments, and same argument and return types.
o The same set of exceptions in the throws clause.
• All SBB local objects that represent an SBB entity that does not exist are invalid. An attemp ted
invocation on an invalid SBB local object marks the current transaction for rollback and throws a
javax.slee.TransactionRolledbackLocalException (a subclass of javax.sl-
ee.SLEEException).
• An SBB Developer defined local interface method is a mandatory transactional method (see Sec-
tion 9.6.1). The SLEE throws a javax.slee.TransactionRequiredLocalException
if an SBB Developer defined local interface method of an SBB local object is invoked without a
valid transaction context.
• This method may also throw a javax.slee.SLEEException if the method failed due to a
does not know, in general, whether the corresponding method imple mentation in the SBB abstract
class was invoked. The caller also does not know if the transaction has been marked for rollback.
However, the caller may determine the transaction status by using the getRollbackOnly
method (see Section 6.10.3).
• The SBB Developer defined SBB local interface methods must not throw java.rmi.Remote-
Exception, any subclass of RemoteException, or any RuntimeException. For more
information on exception handling for SBB local object invocations, see Section 6.9.
• Parameters to local interface methods are passed by reference.
• Note that the SbbLocalObject does not expose the methods of the javax.slee.Sbb inter-
face, event handler methods, or the various callback methods. These methods are used by the
SLEE to manage SBB object instances, deliver events, and handle callbacks.
The following example illustrates two SBB local interfaces:
public interface ControlDelegate extends SbbLocalObject{
public void startWithActivity(ActivityContext ac, ControlCoordinator coordinator)
throws UnacceptableActivityException;
}
public interface ControlCoordinator extends SbbLocalObject{

public void doneWithActivity(ActivityContext ac, ControlDelegate delegate)
throws UnknownDelegateException;
}

Chapter 6
The SBB Abstract Class
Chapter 6 The SBB Abstract Class

The SBB abstract class of the SBB component contains the event processing logic and synchronously in-
voked logic of the SBB component. The SBB Developer must implement an SBB abstract class for every
SBB comp onent. An instance of the SLEE generated class that extends the SBB abstract class is known as
an SBB object. Each SBB object has a life cycle (see Section 6.2).
SBB objects may be pooled. During the lifetime of an SBB object, it may be assigned to different SBB
entities. When the SBB object is assigned to an SBB entity, it can receive events destined for the SBB en-
tity and can manipulate the persistent state of the SBB entity. It can also access the relationships of the SBB
entity.
6.1 Overview
The SBB Developer implements the SBB abstract class. The requirements for an SBB abstract class is as
follows:
• The class must implement, directly or indirectly, the javax.slee.Sbb interface.
• The class must be defined as public and must be abstract.
• The class must not define the finalize method.
The SBB Developer defines the following concrete and abstract methods in the SBB abstract class.
6.1.1 Concrete methods

These methods contain the application logic of the SBB component. These methods include:
• A public constructor.
The SBB Developer must provide a public constructor that takes no arguments.
• Life cycle methods.
Each SBB object has a life cycle. The SLEE invokes the life cycle methods of the SBB object to
make the SBB object aware of its life cycle state. The SLEE invokes a life cycle method before
the SLEE moves the SBB object from one life cycle state to another life cycle state. An SBB en-
tity is assigned to an SBB object when the SBB object is in the Ready state. The life cycle states
and life cycle methods are described in Section 6.2 and Section 6.3, respectively. The base Sbb
interface declares the method signatures of these methods.
• Event handler methods.
The SBB Developer implements an event handler method for each event type that may be received
by the SBB. Each event handler method contains the application logic for processing events of a
specific event type. The event handler methods are described in Section 8.4.2.
• Local interface methods.
If the SBB Developer defines an SBB local interface, i.e. an interface that extends the SbbLo-
calObject interface, then the SBB Developer must implement each SBB Developer defined lo-
cal interface method in the SBB abstract class (see Section 5.6).
• An sbbExceptionThown callback method.
The SBB Developer may implement an sbbExceptionThrown callback method. The SLEE
invokes this method after a SLEE originated invocation of a transactional method of an SBB
object returns by throwing a RuntimeException (see Section 6.9.3).
• An sbbRolledBack callback method.
The SLEE invokes this method after the SLEE rolls back a transaction that was used to invoke a
transactional method of an SBB Object (see Section 6.10.1).
• Initial event selector methods.
If the SBB Developer defines an initial event selector method for an initial event type, the SLEE
Chapter 6
invokes this method for each event of the event type. The return value of this method invocation
determines whether one or more new root SBB entities will be instantiated to process this event
6.1.1.1 At-most-once invocation semantics

All the above methods have at-most-once invocation semantics. If an invocation of one of these methods
fails, the SLEE must not re-invoke the method. For example, the SLEE must not re -invoke a method if the
method returns by throwing a checked or RuntimeException, or if the transaction that the method was
invoked within does not commit.
6.1.2 Abstract methods

These methods are not defined in the base Sbb interface because the signatures of these methods are de-
pendent on the specific SBB. The SLEE provides the implementation of these methods when the SBB is
installed into the SLEE as part of a deployable unit. The SLEE uses introspection of the SBB abstract class
and the definitions in the SBB deployment descriptor to determine and generate the appropriate logic to
interface the SBB to the SLEE. These methods include:
• Fire event methods.
The SBB Developer defines an abstract method for each event type that may be fired by the SBB.
For each fire event method, the event type fired by the fire event method determines its method
name and the Java type of its event object parameter. The SLEE provided implementation of a
fire event method contains the logic to pass the event being fired to the subsystem within the
SLEE that performs event routing. The fire event methods are described in Section 8.4.1.
• CMP field get and set accessor methods.
The SBB Developer uses CMP fields to access the per-instance persistent state (i.e. the SBB en-
tity). CMP fields allow the SLEE to manage the data stored in these fields.For example an im-
plementation could make the state highly available by replicating data to other nodes in a distrib-
uted SLEE or could store the data in a persistent stable store. The SBB Developer declares a set
of abstract get and set accessor methods for each CMP field. The CMP field being accessed de-
termines the name of the accessor methods and the Java type of the CMP field determines the re-
turn type of the get accessor method and the input argument type of the set accessor method. The
SLEE provided implementation of a CMP field accessor method contains the glue logic to access
the data maintained by the subsystem within the SLEE that manages data persistence. See Section
6.4.3 for a more detailed description of CMP fields and their accessor methods.
• Get child relation methods.
The SBB Developer declares a get child relation method for each child relation of the SBB. An
SBB entity uses a get child relation method to get access to a ChildRelation object. The SBB
entity invokes the ChildRelation object to create child SBB entities of the child relation. The
SBB entity can also enumerate the child SBB entities of the child relation (See Section 6.8).
• Get Profile CMP methods.
The SBB Developer declares a get Profile CMP method for each Profile CMP interface that the
SBB may access. A get Profile CMP method takes a Profile identifier argument and returns an
object that implements the declared Profile CMP interface (See Section 6.7).
• An asSbbActivityContextInterface method.
If the SBB Developer defines an SBB Activity Context Interface, then the SBB abstract class
should declare an asSbbActivityContextInterface method. The SBB uses this method
to narrow an object that implements the generic ActivityContextInterface to an object
that implements the SBB Activity Context Interface so that the SBB can access the Activity Con-
text attributes defined in the SBB Activity Context Interface (see Section 7.7.2).
• Get SBB Usage Parameter methods.
If the SBB Developer defines an SBB Usage Parameters interface, then the SBB abstract class

Chapter 6
should declare at least one of the two get SBB Usage Parameters methods. Each of these methods
return an object that implements the SBB Usage Parameters interface of the SBB. This allows the
SBB to manipulate the usage parameters named by the SBB (see Section 0).
6.2 SBB object life cycle

An SBB object can be in one of the following three states (see Figure 5).
• Does Not Exist state.
An SBB object does not exist. It may not have been created or it may have been deleted.
• Pooled state.
An SBB object is not assigned to any particular SBB entity.
• Ready state.
An SBB object in the Ready state is assigned to an SBB entity. It is ready to receive events
through its event handler methods, local method invocations, and various callback method invoca-
tions.
Does Not Exist
1. newInstance
2. setSbbContext unsetSbbContext
Pooled
sbbExceptionThrown
sbbCreate sbbPassivate sbbRemove

sbbPostCreate sbbActivate
Ready
sbbLoad sbbStore
event handler method invocations

local interface method invocations
Figure 5 Life cycle of an SBB object
The following steps describe the life cycle of an SBB object:
• An SBB object’s life cycle starts when the SLEE creates the object using newInstance. The
SLEE then invokes the setSbbContext method to pass the SBB object an SbbContext ob-
ject. The SbbContext object allows the SBB object to invoke functions provided by the SLEE.
• The SBB object enters the pool of available SBB objects. Each SBB component has its own pool.
While the SBB object is in the available pool, the SBB object is not associated with any particular

Chapter 6
SBB entity. All SBB objects in the pool are considered equivalent, and therefore any SBB object
can be assigned by the SLEE to an SBB entity during the transition to the Ready state.
• An SBB object transitions from the Pooled state to the Ready state when the SLEE selects that
SBB object to process an event or to service a logic object invocation. There are two possible tran-
sitions from the Pooled state to the Ready state: through the sbbCreate and sbbPostCreate
methods, or through the sbbActivate method. The SLEE invokes the sbbCreate and
sbbPostCreate methods when the SBB object is assigned to a new SBB entity that has just
been created explicitly by an invocation of the create method on a ChildRelation object or
implicitly by the SLEE to process an initial event. The SLEE invokes the sbbActivate method
on an SBB object when an SBB object needs to be activated to receive a method invocation on an
existing SBB entity. This occurs when there is no existing SBB object in the Ready state assigned
to the SBB entity.
• When an SBB object is in the Ready state, the SBB object is associated with a specific SBB entity.
While the SBB object is in the Ready state, the SLEE can synchronize the transient state held in
the SBB object with the persistent state of the SBB entity whenever it determines the need to, by
invoking the sbbLoad and sbbStore methods zero or more times. Event handler, local inter-
face, exception callback, and transaction rolled back callback methods can be invoked on the SBB
object zero or more times. Invocations of the sbbLoad and sbbStore methods can be arbitrar-
ily mixed with invocations of these methods subject to the SBB object life cycle .
• The SLEE can choose to passivate an SBB object. To passivate an SBB object, the SLEE first in-
vokes the sbbStore method to allow the SBB object to prepare itself for the synchronization of
the SBB entity’s persistent state with the SBB object’s transient state, and then the SLEE invokes
the sbbPassivate method to return the SBB object to the Pooled state.
• Eventually, the SLEE will transition the SBB object to the Pooled state. There are three possible
normal transitions from the Ready state to the Pooled state: through the sbbPassivate method,
through the sbbRemove method, and because of a transaction rollback for sbbCreate or
sbbPostCreate (not shown in above SBB object life cycle state diagram). The SLEE invokes
the sbbPassivate method when the SLEE wants to disassociate the SBB object from the SBB
entity without remo ving the SBB entity. The SLEE invokes the sbbRemove method when the
SLEE wants to remove the SBB entity (i.e. when the SBB entity is removed as part of a cascading
removal of an SBB entity sub-tree). If sbbCreate and sbbPostCreate are called and suc-
cessfully return without throwing a RuntimeException or CreateException, and subse-
quently the enclosing transaction rolls back, the SLEE will transition the SBB object to the Pooled
state by invoking the sbbPassivate method.
• When the SBB object is put back into the pool, it is no longer associated with the SBB entity. The
SLEE can assign the SBB object to any SBB entity of the same SBB component.
• The SLEE may release its references to an SBB object in the pool, allowing it to be garbage col-
lected, after calling the unsetSbbContext method on the SBB object.
Notes:
1. The SbbContext object passed by the SLEE to the SBB object in the setSbbContext
method is not an object that contains static information. For example, the result of the
getSbbLocalObject method might be different each time an SBB object moves from the
Pooled state to the Ready state, and the result of the getActivities method may be different
in different event handler method invocations.
2. A RuntimeException thrown from any method of an SBB object (including the event handler
methods, the local interface methods, and the life cycle callbacks invoked by the SLEE) results in
the transition to the Does Not Exist state after the appropriate exception handler methods have
been invoked (see Section 6.7). The SLEE will not invoke any method except the sbbExcep-
tionThrown method on the SBB object after a RuntimeException has been caught. The

Chapter 6
corresponding SBB entity continues to exist. The SBB entity can continue to receive events and
synchronous invocations because the SLEE can use a different SBB object to process events and
synchronous invocations that should be sent to the SBB entity. Exception handling is described
further in Section 6.9.
3. A SLEE implementation is not required to maintain a pool of SBB objects in the Pooled state. The
pooling approach is an example of a possible implementation, but it is not the required implemen-
tation. Whether the SLEE implementation uses a pool or not has no bearing on the SBB abstract
class coding style.
6.3 SBB abstract class life cycle methods

The SBB Developer is responsible for implementing the following life cycle methods in the SBB abstract
class:
6.3.1 setSbbContext method

The Sbb interface defines the method signature of the setSbbContext method as follows:
public void setSbbContext(SbbContext context);
The SLEE invokes this method after a new instance of the SBB abstract class is created. It uses this method
to pass an SbbContext object to the SBB object. If the SBB object needs to use the SbbContext ob-
ject during its lifetime, it must remember the SbbContext object in an instance variable.
During this method, an SBB entity has not been assigned to the SBB object. The SBB object can take ad-
vantage of this method to allocate and initialize state or connect to resources that are to be held by the SBB
object during its lifetime. Such state and resources cannot be specific to an SBB entity because the SBB
object might be reused during its lifetime to serve multiple SBB entities.
• The setSbbContext method must be declared as public and cannot be static, ab-
stract, or final .
• The SBB object must not attempt to access its persistent state using the CMP field accessor meth-
ods during this method
• This method is invoked with an unspecified transaction context (see Section 9.7.1 for details on
how the SLEE executes methods with an unspecified transaction context).
6.3.2 unsetSbbContext method

The Sbb interface defines the method signature of the unsetSbbContext method as follows:
public void unsetSbbContext();
The SLEE invokes this method before terminating the life of the SBB object. During this method, an SBB
entity is not assigned to the SBB object. The SBB object can take advantage of this method to free state or
resources that are held by the SBB object. These state and resources typically had been allocated by the
setSbbContext method.
• The unsetSbbContext method must be declared as public and cannot be static, ab-
stract, or final .
ods during this method.
• This method is invoked with an unspecified transaction context.
6.3.3 sbbCreate method

The Sbb interface defines the method signature of the sbbCreate method as follows:
public void sbbCreate() throws javax.slee.CreateException;

Chapter 6
The SLEE invokes this method on an SBB object before the SLEE creates a new SBB entity in response to
an initial event or an invocation of the create method on a ChildRelation object. This method
should initialize the SBB object using the CMP field get and set accessor methods, such that when this
method returns, the persistent representation of the SBB entity can be created.
• The sbbCreate method must be declared as public and cannot be static, abstract, or
final.
• This method should throw a javax.slee.CreateException when there is an application
level problem (rather than SLEE or system level problem). If this method throws this exception,
then the SLEE will not create the SBB entity. The SLEE will also propagate the CreateExcep-
tion unchanged to the caller that requested the creation of the SBB entity. The caller may be the
SLEE or an SBB object. The throws clause is mandatory.
• The SLEE guarantees that the values that will be initially returned by the SBB object’s CMP field
get methods will be the Java language defaults (e.g. 0 for integer, null for object references).
• The SLEE invokes this method with a transaction context (see Section 9.6). After this method re-
turns, and in the same transaction context, the SLEE creates the persistent representation of the
SBB entity.
• Child SBB entities should not be created in this method.. This method is invoked before the per-
sistent representation of the new SBB entity is created so the SLEE may not be able to maintain
the relation between the new SBB entity and its child SBB entities. Child SBB entities should in-
stead be created in the sbbPostCreate method or in event handling or local invocation meth-
ods.
6.3.4 sbbPostCreate method

The Sbb interface defines the method signature of the sbbPostCreate method as follows:
public void sbbPostCreate() throws javax.slee.CreateException;
The SLEE invokes this method on an SBB object after the SLEE creates a new SBB entity. The SLEE in-
vokes this method after the persistent representation of the SBB entity has been created and the SBB object
is assigned to the created SBB entity. This method gives the SBB object a chance to initialize additional
transient state and acquire additional resources that it needs while it is in the Ready state.
• The sbbPostCreate method must be declared as public and cannot be static, ab-
stract, or final .
• This method may throw a javax.slee.CreateException when there is an application
level problem (rather than SLEE or system level problem). The SLEE will propagate the Cre-
ateException unchanged to the caller that requested the creation of the SBB entity. The caller
may be the SLEE or an SBB object. The throws clause is optional.
• The SLEE invokes this method with the transaction context (see Section 9.6) used to invoke the
sbbCreate method.
• The SBB entity enters the Ready state when sbbPostCreate returns normally. If sbbPost-
Create returns by throwing an exception, the SBB entity does not become Ready.
6.3.5 sbbActivate method

public void sbbActivate();
The SLEE invokes this method on an SBB object when the SLEE picks the SBB object in the pooled state
and assigns it to a specific SBB entity. This method gives the SBB object a chance to initialize additional
transient state and acquire additional resources that it needs while it is in the Ready state.
• The sbbActivate method must be declared as public and cannot be static, abstract,
or final.
Chapter 6
• This method executes with an unspecified transaction context.
6.3.6 sbbPassivate method

public void sbbPassivate();
The SLEE invokes this method on an SBB object when the SLEE decides to disassociate the SBB ob ject
from the SBB entity, and to put the SBB object back into the pool of available SBB objects. This method
gives the SBB object the chance to release any state or resources that should not be held while the SBB
object is in the pool. These state and resources typically had been allocated during the sbbActivate
method.
• The sbbPassivate method must be declared as public and cannot be static, abstract,
or final.
• This method executes with an unspecified transaction context.
6.3.7 sbbRemove method

public void sbbRemove();
The SLEE invokes the sbbRemove method on an SBB object before the SLEE re moves the SBB entity
assigned to the SBB object. The SLEE removes an SBB entity when the SBB sub-entity tree or SBB entity
tree that the SBB entity belongs to is removed explicitly by an invocation of the remove method on an
SBB local object or implicitly by the SLEE when the attachment count of root SBB entity decrements to
zero. The SBB object is in the Ready state when sbbRemove is invoked and it will enter the pooled state
when the method completes. The SBB Developer can use this method to implement any actions that must
be done before the SBB entity’s persistent representation is removed.
• The sbbRemove method must be declared as public and cannot be static, abstract, or
final.
• The SLEE synchronizes the SBB object’s state before it invokes the sbbRemove method. This
means that the CMP state of the SBB object at the beginning of this method is the same as it
would be at the beginning of an event handler method or a local interface method.
• This method is invoked with a transaction context. After this method returns, and in the same
transaction context, the SLEE executes the internal operations that delete the persistent representa-
tion of the SBB entity.
• Since the SBB object will be entered into the pool of available SBB objects, the state of the SBB
object at the end of this method must be equivalent to the state of a passivated SBB object. This
means that the SBB object must free any state and release any resource that it would normally re-
lease in the sbbPassivate method.
6.3.8 sbbLoad method

public void sbbLoad();
The SLEE calls this method to synchronize the state of an SBB object with its assigned SBB entity’s per-
s istent state. The SBB Developer can assume that the SBB object’s persistent state has been loaded just
before this method is invoked. It is the responsibility of the SBB Developer to use this method to re-
compute or initialize the values of any transient instance variables that depend on the SBB entity’s persis-
tent state. In general, any transient state that depends on the persistent state of an SBB entity should be re-
calculated in this method. The SBB Developer can use this method, for instance, to perform some computa-

Chapter 6
tion on the values returned by the CMP field accessor methods, such as converting text fields to more con-
venient objects or binary representations.
• The sbbLoad method must be declared as public and cannot be static, abstract, or fi-
nal.
• The SLEE invokes this method within a transaction context.
6.3.9 sbbStore method

public void sbbStore();
The SLEE calls this method to synchronize the state of the SBB entity’s persistent state with the state of the
SBB object. The SBB Developer should use this method to update the SBB object using the CMP field
accessor methods before its persistent state is synchronized. For example, this method may perform con-
version of object or binary data representations to text . The SBB Developer can assume that after this
method returns, the persistent state is synchronized.
• The sbbStore method must be declared a s public and cannot be static, abstract, or
final.
• The SLEE invokes this method within a transaction context.
6.4 SbbContext interface

The SLEE provides each SBB object with an SbbContext object. The SbbContext object gives the
SBB object access to the SBB object’s context maintained by the SLEE, allows the SBB object to invoke
functions provided by the SLEE, and obtain information about the SBB entity assigned to the SBB object.
The SbbContext object implements the SbbContext interface. The SbbContext interface declares
the following methods:
• Methods to access information determined at runtime.
o A getSbbLocalObject method to get an SBB local object that represents the SBB
entity assigned to the SBB object of the SbbContext object.
o A getService method to get a ServiceID object that encapsulates the component
identity of the Service that the SBB entity is a descendent of, i.e. the SBB entity is in an
SBB entity tree whose root SBB entity is instantiated by the SLEE for the child relation
(from SLEE as parent to the root SBB) specified by the Service.
o A getSbb method to get an SbbID object that encapsulates the component identity of
the SBB.
• Activity Context methods.
These methods are discussed in greater detail in Section 7.7.1.
o A getActivities method.
This method returns all the Activity Contexts that the SBB entity assigned to the SBB
object of the SbbContext object is attached to. More precisely, it returns an Activity
Context Interface object for each Activity Context attached to the SBB entity assigned to
the SBB object of the SbbContext object.
• Event mask methods.
These methods are described in Section 8.4.3.
o A maskEvent method.
This method masks event types that the SBB entity assigned to the SBB object of the
SbbContext object no longer wishes to receive from an Activity Context.

Chapter 6
o A getEventMask method.
This returns the set of masked event types for an Activity Context that SBB entity as-
signed to the SBB object of the SbbContext object is attached to.
• Transaction methods.
These methods are described in Section 6.10.
o A setRollbackOnly method.
The SBB Developer uses this method to mark the transaction of the current method in-
vocation for rollback.
o A getRollbackOnly method.
The SBB Developer uses this method to determine if the transaction of the current
method invocation has been marked for rollback.
6.4.1 SbbContext interface getSbbLocalObject method

This method returns an SBB local object that represents the SBB entity assigned to the SBB object of the
SbbContext object.
The method signature for the getSbbLocalObject method is as follows:
SbbLocalObject getSbbLocalObject()
IllegalStateException,
SLEEException;
• The object returned is an object that implements the SBB local interface of the SBB entity. The
SBB object uses Java typecast to narrow the returned object reference (from SbbLocalObject)
to the SBB local interface of the SBB entity.
• The SBB object of the SbbContext object must have an assigned SBB entity when it invokes
this method. Otherwise, this method throws a java.lang.IllegalStateException.
• It is a mandatory transactional method (see Section 9.6.1). Hence, the SBB object must invoke this
method within a transaction. It throws a javax.slee.TransactionRequiredLocal-
Exception if it is invoked without a valid transaction context.
• It throws a javax.slee.SLEEException if the requested operation cannot be performed due
to a system-level failure.
6.4.2 SbbContext interface getService method

This method returns the Service component identifier of the Service for which the SBB object owning the
SbbContext object was instantiated for.
The method signature for the getService method is as follows:
ServiceID getService()
throws SLEEException;
• This method is a non-transactional method. An SBB object may invoke this method at any time to
get the ServiceID object for the SBB.
6.4.3 SbbContext interface getSbb method

This method returns the SBB component identifier of the SBB object for which the SbbContext object
was instantiated for.
The method signature for the getSbb method is as follows:

Chapter 6
SbbID getSbb()
throws SLEEException;
• This method is a non-transactional method. An SBB object may invoke this method at any time to
get the SbbID object for the SBB.
6.5 Container Managed Persistence (CMP)

An SBB entity defines its persistent state as a set of CMP fields. The CMP architecture of the SLEE speci-
fication is based on the CMP architecture of Enterprise JavaBeans 2.0 specification. The primary differ-
ences include:
• SLEE CMP is used to access the persistent state of the SBB entity. The SBB entity and its rela -
tionship to SBB objects is described by the SBB object lifecycle. Unlike EJB entity beans that are
always explicitly created and deleted by application code, the SLEE creates root SBB entities to
receive events, and deletes SBB entity trees that can no longer receive events. The SLEE auto-
matically creates root SBB entities and their persistent state in response to initial events, and the
SLEE auto matically deletes SBB entities in an SBB entity tree and their persistent state when the
SBB entity tree will no longer receive further events. Furthermore, SBB entities and their persis-
tent state do not have an externally visible primary key.
• Typically, EJB CMP is used to represent or model data in databases or back-end legacy applica-
tions. The data modeled by EJB CMP are stored in persistent data stores. On the other hand, SLEE
CMP is used to identify data that should be managed by the SLEE. This allows a SLEE to provide
various durability semantics, e.g. to replicate the data for redundancy when handling system fail-
ures. The SLEE specification does not define how the persistent state of an SBB entity should be
managed. It can be replicated to traditional data sources, like EJB, or may be replicated in the
memory of one or more other nodes within a distributed SLEE, or not replicated at all.
• CMP in EJB 2.0 defines both CMP fields and Container Managed Relationship (CMR) fields. The
SLEE specification does not include CMR.
6.5.1 CMP field accessor method rules

The SBB Developer must observe the following rules when defining the CMP fields of an SBB:
• The CMP field accessor methods must be declared but must not be implemented in the SBB ab-
stract class. From the perspective of the SBB Developer, the CMP fields are virtual fields only,
and are accessed through get and set accessor methods. The SLEE supplies the implementation of
the CMP fields.
• The CMP fields must be specified in the SBB’s deployment descriptor using the cmp-field
elements respectively. The names of these fields must be valid Java identifiers and must begin
with a lowe rcase letter, as determined by java.lang.Character.isLowerCase.
• The SBB Developer must declare the accessor methods for the CMP fields as get and set methods,
using the JavaBeans conventions. The SLEE supplies the implementation of the accessor methods.
• The accessor methods must be public, must be abstract, and must bear the name of the
CMP field that is specified in the cmp-field deployment descriptor element, and in which the
first letter of the name of the CMP field has been uppercased and prefixed by “get” or “set”.
• The Java types of the CMP fields are restricted to Java primitive types, Java serializable types, and
SBB local interfaces (i.e., SbbLocalObject and the types derived from SbbLocalObject).
Since the SLEE specification does not require the SBB local interface or its derived types to be se-
rializable, non-primitive CMP field types cannot contain SBB local interface types. For example,
a composite object that contains one or more SBB local interface member types or an SBB local
interface array are not valid CMP field types.

Chapter 6
• Logically, setting an SBB local object into a CMP field stores a reference to the SBB entity repre-
sented by the SBB local object. The SLEE maintains referential integrity for SBB entity references
stored in CMP fields. If the target SBB entity of a reference is deleted, the SLEE must in future re-
turn null from any CMP field accessor for a CMP field that referenced the target SBB entity.
• CMP fields that hold SBB entity references.
o If the Java type of the CMP field is an SBB local interface (i.e., SbbLocalObject, or
a type derived from SbbLocalObject ), then the sbb-alias-ref ele ment must be
present. An sbb-alias-ref element cannot be declared for a CMP field of a Java
type other than SbbLocalObject or a type derived from SbbLocalObject.
o The Java type of the CMP field must be the same type or a base type of the SBB local in-
terface of the SBB component specified by the sbb-alias-ref element.
o If the sbb-alias-ref element is present, only null and references to valid SBB en-
tities of the SBB component identified by the sbb-alias-ref element can be stored
in the CMP field. The SLEE implemented set accessor method must throw the
java.lang.IllegalArgumentException if any other SBB entity reference, or
an invalid reference to an SBB entity of the SBB component identified by the sbb-
alias-ref element, is passed to the set accessor method.
• The CMP field accessor methods are mandatory transactional methods (see Section 9.6.1). They
throw a javax.slee.Trans actionRequiredLocalException if they are invoked
without a valid transaction context.
• These methods may also throw a javax.slee.SLEEException if the operation cannot be
completed due to a system-level failure.
• Neither the get accessor method nor the set accessor method can include a throws clause.
6.5.2 CMP field example

The following example illustrates two CMP fields and their get and set accessor methods.
The deployment descriptor for the example Foo SBB is as follows:
<sbb>
…
<description> FooSbb … </description>
<sbb-alias> FooSbb </sbb-alias>
…
<sbb-classes>
…
com.foobar.FooSbb
<cmp-field>
<description>
An integer counter.
</description>
<cmp-field-name> counter </cmp-field-name>
</cmp-field>
<cmp-field>
<description>
The most recent time that the counter was updated.
</description>
<cmp-field-name> counterLastUpdated </cmp-field-name>
</cmp-field>
<cmp-field>
<description>

Chapter 6
Holds a reference to my peer FooSBB.
</description>
<cmp-field-name> peerFooSbb </cmp-field-name>
<sbb-alias-ref> FooSbb </sbb-alias-ref>
</cmp-field>
…
…
</sbb-classes>
…
</sbb>
The Foo SBB abstract class is as follows:
package com.foobar;
…
import java.util.Date;
…
public abstract FooSbb implements javax.slee.Sbb {
…
/* accessor methods for counter CMP field */
public abstract int getCounter();
public abstract void setCounter(int value);
/* accessor methods for counterLastUpdated CMP field */

public abstract Date getCounterLastUpdated();
public abstract void setCounterLastUpdated(Date value);
/* accessor methods for FooSbbLocalObject CMP field */

public abstract FooSbbLocalObject getPeerFooSbb();
public abstract void setPeerFooSbb(FooSbbLocalObject value);
…
}
6.6 Non-persiste nt state

The SBB Developer may also declare instance variables in the SBB abstract class to maintain non-
persistent state. The SBB Developer can use instance variables to store values that depend on the persistent
state of the SBB entity, although this use is not encouraged. The SBB Developer should use the sbbLoad
method to resynchronize the values of any instance variables that depend on the SBB entity’s persistent
state. In general, any non-persistent state that depends on the persistent state of an SBB entity should be
recomputed during the sbbLoad method.
6.7 SBB abstract class get Profile CMP methods

The SBB Developer declares a get Profile CMP method for each Profile Specification that the SBB may
use and provides a deployment descriptor to specify the Profile Spec ification of the get Profile CMP
method.
The method signature of this method is as follows:
public abstract <Profile CMP interface> <get Profile CMP method name>
(ProfileID profileID)
throws UnrecognizedProfileTableNameException,
UnrecognizedProfileNameException;
• The method must be declared as public and abstract. The SLEE provides the concrete im-
plementation of the get Profile CMP method when the SBB is deployed.
• The method name must not begin with “sbb” or “ejb”, and must be a valid Java identifier.
• The Java type of the only input argument must be ProfileID.
When the SBB invokes this method with a ProfileID object, the ProfileID object should
uniquely identify a Profile that is in a Profile Table created from the Profile Specification.

Chapter 6
o It throws a javax.slee.profile.UnrecognizedProfileTableName-
Exception if the ProfileID object does not identify a Profile Table created from
the Profile Specification.
o If the Profile identifier identifies a Profile Table created from the Profile Specification,
then this method throws a javax.slee.profile.UnrecognizedProfile-
NameException if the ProfileID object does not identify a Profile within the Pro-
file Table.
• The return type must be the Profile CMP interface of the Profile Specification, or a base interface
of the Profile CMP interface of the Profile Specification.
The SBB uses the returned Profile CMP object to access the attributes of the Profile identified by
the input argument.
• The SBB object must have an as signed SBB entity when it invokes this method. Otherwise, this
method throws a java.lang.IllegalStateException. This exception is not declared in
the throws clause.
Exception if it is invoked without a valid transaction context. This exception is not declared in
the throws clause.
to a system-level failure. This exception is not declared in the throws clause.
The get-profile-cmp-method deployment descriptor element declares the presence of the get Pro-
file CMP method and associates the method with a Profile Specification. This SBB Developer specifies the
following aspects of the get Profile CMP method using the get-profile-cmp-method element:
• The method name of the get Profile CMP method.
• The Profile Specification of the get Profile CMP method.
6.8 SBB abstract class get child relation methods

For each child relation of the SBB, the SBB Developer must declare an abstract get child relation method in
the SBB abstract class and include a get-child-relation-method deployment descriptor element
in the SBB’s deployment descriptor.
The method signature of a get child relation method is as follows:
public abstract ChildRelation <get child relation method name>();
• The method must be public and abstract. The SLEE provides the concrete implementation
of the get child relation method when the SBB is deployed.
• The method name must not begin with “sbb” or “ejb”.
• The method does not have a throws clause.
• The return type must be javax.slee.ChildRelation. An SBB entity invokes the returned
ChildRelation object to create child SBB entities and enumerate child SBB entities that be-
long to this relation (see Section 6.8.1 ).
• The ChildRelation object and its Iterator objects are only valid within the same transac-
tion in which the ChildRelation object was obtained.
• The name of the method, i.e. <get child relation method name>, must be a valid Java
identifier.
• The method must not throw any checked exceptions.

Chapter 6
• The SBB object must have an assigned SBB entity when it invokes this method. Otherwise, this
method throws a java.lang.IllegalStateException.
The get-child-relation-method deployment descriptor element declares the child relation from
the SBB to the child SBB. This SBB Developer specifies the following aspects of the child relation using
the get-child-relation-method element:
• The child SBB of the child relation, i.e. the SBB that plays the child role in this child relation.
• The method name of the get child relation method for this child relation.
• The default event delivery priority of the child relation.
6.8.1 ChildRelation interface

A ChildRelation object is an instance of a class that implements the ChildRelation interface. The
SLEE provides the implementation of this class.
The ChildRelation interface is as follows:
package javax.slee;
public interface ChildRelation extends Collection {

SbbLocalObject create()
throws CreateException,
SLEEException;
}
6.8.2 ChildRelation interface create method

An SBB object that represents an SBB entity of a parent SBB invokes this method to create a new child
SBB entity on a child relation.
• The actual object returned by this method is an object that implements the SBB local interface of
the child SBB. The parent SBB uses Java typecast to narrow the returned object reference (from
SbbLocalObject) to the SBB local interface of the child SBB.
• If this method returns by throwing a javax.slee.CreateException (or a subclass of
CreateException), the CreateException indicates that an application-level error oc -
curred. If a caller of this method receives this exception, the caller does not know, in general,
whether the SBB entity was created but not fully initialized, or not created at all. Also, the caller
does not know whether or not the transaction has been marked for rollback. However, the caller
may determine the transaction status by using the getRollbackOnly method (see Section
6.10.3).
context.
• This method throws a javax.slee.SLEEException if the child SBB entity could not be
created due to a system-level failure.

Chapter 6
6.8.3 ChildRelation interface Collection methods

A ChildRelation object is also a collection that contains a set of SBB local objects that represent each
child SBB entity of the child relation.
• The size method.
o This method returns the number of child SBB entities in this child relation.
• The isEmpty method.
o This method returns true if there are no child SBB entities in this child relation.
• The contains method.
o This method returns true if the SBB entity represented by the SBB local object speci-
fied by the input argument is a member of this child relation. If the method argument is
not an SBB local object, is an invalid SBB local object, or is an SBB local object whose
underlying SBB entity is not a member of this child relation, then this method returns
false.
• The containsAll method.
o This method returns true if all SBB entities represented by the SBB local objects in the
collection specified by the input argument are members of this child relation. If the col-
lection contains an object that is not an SBB local object, an SBB local object that is
invalid, or an SBB local object whose underlying SBB entity is not a member of this
child relation, then this method returns false.
• The toArray methods.
o The SLEE must implement these methods by following the contract defined by the
java.util.Collection interface. The ordering of the elements in the returned ar-
rays is unspecified.
• The add methods: add and addAll.
o Any attempts to add to the child relation using these methods result in a java.la-
ng.UnsupportedOperationException. For example, the SLEE must throw the
UnsupportedOperationException when these methods are invoked with argu-
ments that add to the collection.
o An invocation of an add method that has no effect on the collection, such as invoking the
addAll method with an empty collection may or may not throw an UnsupportedOp-
erationException .
o The create method of the ChildRelation interface should be used to create a child
SBB entity. This causes the SLEE to automatically add an SBB local object that repre-
sents the newly created SBB entity to the collection.
• The remove methods: clear, remove, removeAll, and retainAll.
o These methods may remove SBB entities from the child relation. The input argument
specifies which SBB entities will be removed from the child relation or retained in the
child relation by specifying the SBB local object or collection of SBB local objects that
represent the SBB entities to be removed or retained.
o Removing an SBB entity from a child relation initiates a cascading removal of the SBB
entity tree rooted by the SBB entity, similar to invoking the remove method on an SBB
local object that represents the SBB entity.
• The iterator method and the Iterator objects returned by this method.

Chapter 6
o The SLEE must implement the methods of the Iterator objects returned by the it-
erator method by following the contract defined by the java.util.Iterator in-
terface.
o The next method of the Iterator object returns an object that implements the SBB
local interface of the child SBB of the child relation. Java typecast can be used to narrow
the returned object reference to the SBB local interface of the child SBB.
o The remove method of the Iterator object removes the SBB entity that is repre-
sented by the las t SBB local object returned by the next method of the Iterator ob-
ject from the child relation.
§ Removing an SBB entity from a child relation by invoking this remove method
initiates a cascading removal of the SBB entity tree rooted by the SBB entity,
similar to invoking the remove method on an SBB local object that represents
the SBB entity.
§ The behavior of the Iterator object is unspecified if the underlying child re-
lation is modified while the iteration is in progress in any way other than by call-
ing this remove method.
• The ChildRelation object and its Iterator objects are only valid within the same transac-
tion that invoked the get child relation method to obtain the ChildRelation object.
• If any of the argu ments to one of these methods are null, then the method throws a java.la-
ng.NullPointerException.
6.8.4 Transactional semantics

The methods of the ChildRelation interface have mandatory transactional semantics. Hence, these
methods must be invoked within a transaction (see Section 9.6.1).
• If a child SBB entity is created, its effect is only visible within the same transaction, i.e. the
ChildRelation object will contain an SBB local object that represents the recently created
SBB entity.
o If the transaction commits, the new child SBB entity will be visible to subsequent trans-
actions.
o If the transaction aborts, the new child SBB entity will cease to exist and will not be visi-
ble to subsequent transactions.
• Similarly if an SBB entity is removed, its effect is only visible within the same transaction, i.e. the
ChildRelation object returned will not contain an SBB local object that represents the re-
moved SBB entity and CMP fields that reference this SBB local object will be set to null. The
SLEE will mark the transaction for rollback and throw a javax.slee.Transaction Roll-
edbackLocalException if an SBB local object that represents the removed SBB entity is in-
voked.
o If the transaction commits, the removed child SBB entity will cease to exist permanently
and will be invisible to subsequent transactions.
o If the transaction aborts, the “removed” child SBB is not removed and will continue to be
visible to subsequent transactions.
6.9 SBB abstract class exception callback method

The SLEE invokes the sbbExceptionThrown callback method to handle RuntimeExceptions
thrown by the event handler methods, the transaction rolled back callback method and the logical cascade-
removal method of the SBB abstract class.

Chapter 6
A well-written SBB should not throw any RuntimeExceptions from any of its SLEE invoked methods.
Instead, the SBB should place the exception handling logic inside a try { } catch (Throwable)
clause and handle RuntimeExceptions within each invoked method.
6.9.1 Runtime Exception handling for transactional methods

When a SLEE originated mandatory transactional method is invoked on an SBB object and the invocation
returns with a RuntimeException thrown, the SLEE performs the following actions:
• The SLEE marks the transaction of the invocation for rollback.
• The SLEE should log this condition.
• The SLEE invokes the sbbExceptionThrown method of the same SBB object with the same
transaction. The SBB object may in the Pooled state or in the Ready state. For example, if a
sbbCreate method throws the RuntimeException, then the SBB object remains in the
Pooled state when the SLEE invokes the sbbExceptionThrown method on the SBB object. If
an event handler method throws the RuntimeException, then the SBB object remains in the
Ready state when the SLEE invokes the sbbExceptionThrown method on the SBB object.
• The SLEE moves the SBB object to the Does Not Exist state.
• If the mandatory transactional method was invoked as a result of an SBB object invoking a
method on an SBB local object (i.e. non-SLEE originated invocation as defined Section 9.8), then
the SLEE throws a javax.slee.TransactionRolledBackLocalException to the
caller that invoked the SBB local object.
• If the sbbExceptionThrown method of the SBB object returns with another Runtime-
Exception thrown, the SLEE must log this condition. The sbbExceptionThrown method is
not reinvoked in this case.
Section 6.13 summarizes which SBB abstract class methods are mandatory transactional methods. Seman-
tics of mandatory transactional methods are described in Section 9.6.1.
6.9.2 Runtime Exception handling for non-transactional methods

When the SLEE invokes a non-transactional method of an SBB object and the invocation returns by throw-
ing a RuntimeException, the SLEE performs follo wing sequence of operations.
• The SLEE moves the SBB object to the Does Not Exist state.
• The SLEE must log this occurrence.
Section 6.15 summarizes which SBB abstract class methods are non-transactional methods.
6.9.3 SBB abstract class sbbExceptionThrown method

The SBB Developer implements the sbbExceptionThrown method in the SBB abstract class. The
sbbExceptionThrown method has the following method sig nature:
public void sbbExceptionThrown(Exception exception,
Object event,
ActivityContextInterface activity);
• The sbbExceptionThrown method must be declared as public and cannot be static ,
abstract, or final.
• The exception argument is the exception thrown by one of the methods invoked by the SLEE,
e.g. a life cycle method, an event handler method, or a local interface method.
• If the method that threw the exception is an event handler method, the event and activity ar-
guments will be the event and activity arguments of the event handler method. Otherwise,
the event and activity arguments will be null.

Chapter 6
• The sbbExceptionThrown method is a mandatory transactional method.

• The SLEE does not invoke the sbbExceptionThrown method if a non-transactional method
invocation returns by throwing a RuntimeException.
• The sbbExceptionThrown method may be invoked on an SBB object in the Ready state. The
state of the SBB object remains the same, it is the state at the point that the
RuntimeException was thrown. The SBB object moves to the Does Not Exist state after the
sbbExceptionThrown method has been invoked.
6.9.4 SBB abstract class exception callback methods example

package com.foobar;
…
import javax.slee.ActivityContextInterface;
import javax.slee.Sbb;
…
public FooSbb implements Sbb … {
…
public void sbbExceptionThrown(Exception exception,
Object event,
ActivityContextInterface activity) {
// this should not happen, generate trace message
…
// do additional cleanup
…
}
…
}
6.10 SBB abstract class and SbbContext interface transaction methods

The section describes the transaction related methods of the SBB abstract class and the SbbContext in-
terface.
6.10.1 SBB abstract class sbbRolledBack callback method

The SLEE invokes the sbbRolledBack callback method after a transaction used in a SLEE originated
invocation has rolled back (see Section 9.12).
The method signature of the sbbRolledBack method is as follows:
public void sbbRolledBack(RolledBackContext context);
• The sbbRolledBack method must be declared as public and cannot be static, ab-
stract, or final .
• This method is invoked with a new transaction context, i.e. not with the transaction context of the
transaction that has been rolled back.
• This method is a mandatory transactional method.
• This method is only invoked on SBB objects in the Ready state.
• If this method returns by throwing an exception, the SLEE processes this exception like the excep-
tion has been thrown from an event handler method, i.e. by invoking the sbbException-
Thrown method in the same transaction.
• In the case that a RuntimeException causes the transaction to be rolled back, the sbb-
RolledBack method is always invoked after the sbbExceptionThrown method since the
sbbExceptionThrown method is invoked in the transaction that will eventually be rolled
back. If the sbbRolledBack method returns by throwing a RuntimeException, then the
sbbExceptionThrown method will be invoked again in the same transaction that invoked the
sbbRolledBack method.
Chapter 6
• If the transaction that invoked the sbbRolledBack method also rolls back, the SLEE must log
this condition and not invoke the sbbRolledBack method again.
• When the SLEE rolls back a transaction, the SLEE may start zero or more new transactions to de-
liver transaction rolled back callbacks.
o If the rolled back transaction does not invoke any SBB entities, i.e. none of the SLEE
originated invocations (see Section 9.8.2) of the transaction (see Section 9.8.3) have a
target SBB entity, then the SLEE does not start any new transactions to deliver transac-
tion rolled back callbacks.
o If the rolled back transaction includes one or more SLEE originated invocations (see Sec-
tion 9.8.2), then the SLEE starts a new transaction to deliver a transaction rolled back
callback for each of the SLEE orig inated invocations in the transaction that has a target
SBB entity.
The SLEE may or may not be successful in delivering a transaction rolled back callback .
For example, if the SLEE does not have already have an SBB object in the Ready state
that represents the target SBB entity, then SLEE has to invoke the necessary life cycle
methods on an SBB object before it can invoke the sbbRolledBack method. The SLEE
does not invoke the sbbRolledBack method if one of these life cycle methods throw a
RuntimeException and cause the new transaction to be rolled back before the SLEE
has an opportunity to invoke the sbbRolledBack method.
For example, the SLEE starts a transaction so that it can invoke an event handler method
of a Foo SBB. This event handler method directly invoked by the SLEE synchronously
invokes a local interface method of another SBB. The implementation of this local inter-
face method throws a RuntimeException. The SLEE marks the transaction for roll
back. Eventually, the event handler method returns (whether by throwing an exception or
normally). The SLEE eventually starts a new transaction to invoke the sbbRolled-
Back method of a Foo SBB object.
6.10.1.1 RolledBackContext interface

The RolledBackContext interface is as follows:
package javax.slee;
public interface RolledBackContext {

Object getEvent();
ActivityContextInterface getActivityContextInterface();
boolean isRemoveRolledBack();
};
• The getEvent and getActivityContextInterface methods return null if the transac-
tion that was rolled back did not deliver an event to an SBB. Otherwise, these methods return the
event object and the Activity Context that of the event that should be handled by the transaction
that was rolled back, respectively.
• The isRemovedRolledBack method returns true if the transaction that was rolled back in-
cludes a SLEE originated logical cascading removal method invocation (see Section 9.8.1).
The SLEE originated logical cascading removal method invocation must have been initiated in the
transaction that has been rolled back for this method to return true.
6.10.2 SbbContext interface setRollbackOnly method

An SBB object invokes this method when it is invoked within a transaction to mark the transaction for roll -
back.

Chapter 6
The method signature of the setRollbackOnly method is as follows:
void setRollbackOnly() throws TransactionRequiredLocalException, SLEEException;
• It is a mandatory transactional method. If this method is invoked when the SBB object is not
invoked within a transaction, then the SLEE will throw a javax.slee.Transaction-
RequiredLocalException.
6.10.3 SbbContext interface getRollbackOnly method

An SBB object invokes this method when it is invoked within a transaction to learn if the transaction has
been marked for rollback.
The method signature of the getRollbackOnly method is as follows:
boolean getRollbackOnly() throws TransactionRequiredLocalException, SLEEException;
• It is a mandatory transactional method. If this method is invoked when the SBB object is not
invoked with a transaction, then the SLEE will throw a javax.slee.Transaction-
RequiredLocalException.
6.10.4 SBB abstract class and SbbContext interface transaction methods

example
package com.foobar;
…
import javax.slee.Sbb;
import javax.slee.SbbContext;
import javax.slee.RolledBackContext;
…
public FooSbb implements Sbb … {
…
private SbbContext sbbContext;
…
public void setSbbContext(SbbContext context) {
…
sbbContext = context;
…
}
…
public void onStarted(…) {
…
// touch some CMP fields
…
// if marked for rollback, do …
if (sbbContext.getRollbackOnly()) {
…
return …;
}
…
try {
// do more processing
} catch (…) {
…
// something bad happened, do not commit transaction
sbbContext.setRollbackOnly();
…
}
…
}

Chapter 6
…
public void sbbRolledBack(RolledBackContext ctx){
// generate trace message
…
// do additional cleanup
…
}
…
}
6.11 Non-reentrant and re-entrant SBB components

An SBB Developer can specify that an SBB component is non-reentrant. If an SBB entity of a non-
reentrant SBB component is executing in a given transaction context, and another method invocation with
the same transaction context arrives for the same SBB entity, the SLEE will throw an exception to the sec-
ond request. This rule allows the SBB Developer to program the SBB component as single-threaded non-
reentrant code.
The functionality of SBB components may require loop backs in the same transaction context. An example
of a loop back is when SBB entity A receives a method invocation, A calls SBB entity B, and B calls back
A in the same transaction context. The method invoked by the loop back shares the current execution con-
text (which includes the transaction) with the initial invocation of SBB entity A.
If the SBB component is specified as non-reentrant in the deployment descriptor, the SLEE must reject an
attempt to re-enter the SBB entity while the SBB entity is executing a method invocation. (This can hap-
pen, for example, if the SBB entity has invoked another SBB entity and the other SBB entity tries to make
a loop back call.) If the attempt is made to reenter the SBB entity, the SLEE must throw the javax.sl-
ee.SLEEException to the caller. The SLEE must allow the call if the SBB component’s deployment
descriptor specifies that the SBB component is re-entrant.
Re-entrant SBB components must be programmed and used with caution. First, the SBB Developer must
code the SBB abstract class with the anticipation of a loop back call.
SBB components that do not need callbacks should be marked as non-reentrant in the deployment descrip-
tor, allowing the SLEE to detect and prevent illegal concurrent calls.
6.12 Method name re strictions

Non-private (such as public, protected, or package private) methods that are declared by the SBB Devel-
oper must not begin with “sbb” or “ejb”. A SLEE implementation can use method names that begin with
“sbb” when needed without being concerned with possible method name conflicts with SBB Developer
declared method names.
This restriction does not apply when the SBB Developer implements an “sbb<XXX>” method declared by
the SLEE, such as the life cycle methods declared in the javax.slee.Sbb interface.
6.13 SBB component environment

The component environment of an SBB component provides the runtime environment that is common to all
instances of the classes of the SBB component. The SBB component environment is a mechanism that pro-
vides the following features:
• Access to Facilities defined by the SLEE specification.
• Customization of the SBB component during assembly or deployment using deployment descrip-
tor elements.
This allows an SBB Developer and a Service Deployer to customize an SBB component’s behav-
ior without the need to access or change the SBB component’s source code. The SLEE specifica -
tion defines SBB deployment descriptor elements that add new context information to the comp o-
nent environment of the SBB component. The SBB Developer and the Service Deployer may use
these deployment descriptor elements to provide configuration data that can be determined and
fixed during SBB composition or Service deployment. In addition, SBB components may also ac-
Chapter 6
cess external resources that are dependent on the target operational environment. The Service De-
ployer may use deployment descriptor elements to associate external resources with the SBB
component.
The ability to customize the environment of the SBB component at assembly and deployment allows inde-
pendent software vendors to develop SBB components that are, to a large degree, independent from the
operational environment in which the SBB components will be deployed.
6.13.1 SBB component environment as a JNDI naming context

The SLEE implements the SBB component environment, and provides it to the instances of the SBB com-
ponent classes through the JNDI interfaces. The SBB component environment is used as follows:
• The methods implemented by classes of the SBB component access the component environment
using the JNDI interfaces.
• The SLEE provides an implementation of the JNDI naming context that stores the SBB comp o-
nent environment. The SLEE makes the environment naming context available to the instances of
the classes of the SBB component at runtime. These instances use the JNDI interfaces to obtain
the values of the environment entries.
• The SLEE provides the following environment entries:
o An entry for each SLEE Facility.
o An entry for each SLEE specification defined Activity Context Interface Factory.
• The SBB Developer declares in the SBB deployment descriptor all the environment entries that
the SBB component expects Service Deployers to customize during Service assembly and d e-
ployment.
Each SBB component has its own set of enviro nment entries. All instances of SBB component classes of
the same SBB component share the same environment entries; the environment entries are not shared with
other SBB components. Instances of the classes of the SBB comp onent are not allowed to modify the SBB
component environment at runtime.
Terminology warning: The SBB’s component “environment” should not be confused with the “environment
properties” defined in the JNDI documentation.
6.13.1.1 SBB Developer responsibilities

This section describes the SBB Developer’s view of the component environment, and defines the accompa-
nying responsibilities.
6.13.1.1.1 Access to SBB component environment

SBB Objects locate the environment naming context using the JNDI interfaces. An SBB Object creates a
javax.naming.InitialContext object by using the constructor with no arguments, and looks up
the environment naming via the InitialContext under the name java:comp/env. The SBB co m-
ponent environment entries are stored directly in the environment naming context, or in any of its direct or
indirect subcontexts.
The following table lists the names of the SLEE specification defined environment entries under
java:comp/env.
Objects Returned Java type Names
SLEE Facilities Depends on Facility slee/facilities/...
Resources Depends on resource slee/resources/...
For the environment entries declared by SBB Developers, the value of an environment entry is of the Java
type declared by the SBB Developer in the SBB deployment descriptor.
The following example illustrates how environment entries are accessed.

Chapter 6
package com.foobar;
…
public abstract class FooSbb implements javax.slee.Sbb … {
…
public void onNewConnection(…) {
…
// Obtain the SBB component environment naming context.
Context initCtx = new InitialContext();
Context myEnv = (Context)initCtx.lookup("java:comp/env");
// Obtain the maximum number of connections

// configured by the Service Deployer.
Integer max = (Integer) myEnv.lookup("maxConnections");
// Obtain the minimum number of connections

// configured by the Service Deployer.
Integer min = (Integer) myEnv.lookup("minConnections");
if (numberConnections > Integer.intValue(max) ||

numberConnections < Integer.intValue(min)) {
// terminate connection and return
…
}
// Get some more environment entries. These environment

// entries are stored in subcontexts.
String val1 = (String) myEnv.lookup("foo/name1");
Boolean val2 = (Boolean) myEnv.lookup("foo/bar/name2");
// Can also lookup using full pathnames.

Integer val3 = (Integer)
initCtx.lookup("java:comp/env/name3");
Integer val4 = (Integer)
initCtx.lookup("java:comp/env/foo/name4");
…
}
…
}
6.13.1.1.2 Declaration of environment entries

The SBB Developer must declare all the environment entries accessed from the SBB comp onent’s code.
The environment entries are declared using the env-entry ele ments in the SBB deployment descriptor.
Each env-entry element describes a single environment entry. The env-entry element consists of the
following sub-elements:
• An optional description element that describes the environment entry.
• An env-entry-name element that specifies a name relative to the java:comp/env context.
• An env-entry-type element that specifies the expected Java type of the environment entry
value, i.e. the type of the object returned from the JNDI lookup method.
• An optional env-entry-value element that specifies the value of the environment entry.
• An environment entry is scoped to the SBB comp onent whose declaration contains the env-
entry element. This means that the environment entry is inaccessible from other SBB comp o-
nents at runtime, and that other SBB components may define env-entry elements with the
same env-entry-name without causing a name conflict.
• The environment entry values may be one of the following Java types: String, Character,
Integer, Boolean, Double , Byte, Short, Long, and Float.
• If the SBB Developer provides a value for an environment entry using the env-entry-value
element, the value can be changed later by the SBB Developer or Service Deployer. The value

Chapter 6
must be a string that is valid for the constructor of the specified type that takes a single String
parameter, or for java.lang.Character, a single character.
The following example is the declaration of environment entries used by the Foo SBB whose code was
illustrated in the previous subsection.
<sbb>
…
<sbb-classes>
…
…
com.foobar.FooSbb
…
</sbb-classes>
…
<env-entry>
<description>
The maximum number of connections allowed.
</description>
<env-entry-name> maxConnections </env-entry-name>
<env-entry-type> java.lang.Integer </env-entry-type>
<env-entry-value> 5 </env-entry-value>
</env-entry>
<env-entry>
<description>
The minimum number of connections allowed.
</description>
<env-entry-name> minConnections </env-entry-name>
</env-entry>
<env-entry>
<env-entry-name> foo/name1 </env-entry-name>
<env-entry-type> java.lang.String </env-entry-type>
<env-entry-value> value1 </env-entry-value>
</env-entry>
<env-entry>
<env-entry-name> foo/bar/name2 </env-entry-name>
<env-entry-type> java.lang.Boolean </env-entry-type>
<env-entry-value> true </env-entry-value>
</env-entry>
<env-entry>
<description> Some description. </description>
<env-entry-name> name3 </env-entry-name>
<env-entry-type>java.lang.Integer </env-entry-type>
</env-entry>
<env-entry>
<env-entry-name> foo/name4 </env-entry-name>
</env-entry>
…
</sbb>
6.13.1.2 The Service Deployer’s responsibility

The Service Deployer must ensure that the values of all the environment entries declared by the SBB com-
ponent are set to meaningful values. The Service Deployer can modify the values of the environment en-
tries that have been previously set by the SBB Developer, and must set the values of those environment
entries for which no value has been specified.
The description elements provided by the SBB Developer help the Service Deployer with this task.

Chapter 6
6.13.2 Resource adaptor type defined Activity Context Interface Fa ctory

object references
This section describes the programming interfaces and deployment descriptor elements that allow the SBB
code to refer to resource adaptor type defined Activity Context Interface Factory objects using logical
names called resource adaptor type bindings. These bindings are special entries in SBB component envi-
ronments. The Service Deployer uses these bin dings to bind actual resource adaptor type defined Activity
Context Interface Factory objects at runtime to SBB components.
6.13.2.1 SBB Developer’s responsibilities

This section describes the SBB Developer’s view of locating resource adaptor type defined Activity Con-
text Interface Factory objects and defines the accompanying responsibilities.
6.13.2.1.1 Programming interfaces for resource adaptor type bindings

The SBB Developer must use resource adaptor type bindings to obtain references to resource adaptor type
defined Activity Context Interface Factory objects (see Section 7.6.1) as follows.
• Assign an entry in the SBB’s component environment to the resource adaptor type binding. (See
Section 6.13.2.1.2 for information on how resource adaptor type bindings are declared in the SBB
deployment d escriptor.)
The SLEE specification recommends, but does not require, that all resource adaptor type bindings
be organized in the subcontexts of the SBB’s component environment, using a different subcontext
for each resource adaptor type under the java:comp/env/slee/resources subcontext .
For example, all JCC resource adaptor type bindings might be declared in the
java:comp/env/slee/resources/jcc subcontext, and all JAIN SIP resource adaptor
type bindings in the java:comp/env/slee/resources/sip subcontext.
• Lookup the resource adaptor type defined Activity Context Interface Factory objects in the SBB’s
component environment using the JNDI interface.
The following code sample illustrates obtaining a JCC Activ ity Context Interface Factory object.
{
…
JccCall call = …
…
JccActivityContextInterfaceFactory acif =
(JccActivityContextInterfaceFactory) new InitialContext().lookup
("java:comp/env/slee/resources/jcc/1.1/activitycontextinterfacefactory");
ActivityContextInterface aci = acif.getActivityContextInterface(call);
…
}
6.13.2.1.2 Declaration of resource adaptor type bindings in the SBB deployment

descriptor
Although a resource adaptor type binding is an entry in the SBB’s component environment, the SBB De -
veloper must not use an env-entry element to declare it.
Instead, the SBB Developer must declare all the resource adaptor type bindings in the SBB deployment
descriptor using resource-adaptor-type-binding. This allows the SBB Developer and Service
Deployer to discover all the resource adaptor type bindings used by an SBB component.
Each resource-adaptor-type-binding element describes a single resource adaptor type binding.
The resource-adaptor-type-binding element contains the following sub-elements:
• An optional description element.
• A resource-adaptor-type-ref element identifies the resource adaptor type of the re-
source adaptor type binding. It contains a resource-adaptor-type-name sub-element, a

Chapter 6
resource-adaptor-type-vendor sub-element, and a resource-adaptor-type-
version sub-element. These sub-elements must match exactly the corresponding sub-elements
in the resource-adaptor-type element (see Section 15.1.2) of the resource adaptor type.
The activity-context-interface-factory-interface-name element of re-
source-adaptor-type element specifies the Java type of the Activity Context Interface Fac-
tory object returned from the JNDI lookup method.
• An activity-context-interface-factory-name element contains the name of the
environment entry used in the SBB component’s code to access an Activity Context Interface Fac-
tory object of the resource adaptor type. The name of the environment entry is relative to the
java:comp/env context (e.g. the name should be slee/resources/jcc/… rather than
java:comp/env/slee/resources/jcc/…).
• Zero or more resource-adaptor-entity-binding elements (see Section 6.13.3.1.2),
Each SBB component has its own set of resource adaptor type binding entries. The resource adaptor type
binding environment entries are not shared with other SBB components. The SBB component environment
may not be modified at runtime.
The following example is the declaration of resource adaptor type binding used by the example illustrated
above.
<sbb>
…
<resource-adaptor-type-ref>
<resource-adaptor-type-name>
JCC
</resource-adaptor-type-name>
<resource-adaptor-type-vendor>
javax.csapi.cc.jcc
</resource-adaptor-type-vendor>
<resource-adaptor-type-version>
1.1
</resource-adaptor-type-version>
</resource-adaptor-type-ref>
<activity-context-interface-factory-name>
slee/resource/jcc/1.1/activitycontextinterfacefactory
</activity-context-interface-factory-name>
…
…
</sbb>

The Service Deployer must ensure that the resource-adaptor-type-ref elements of all the re-
source-adaptor-type-binding elements declared by the SBB component are set to meaningful
values. For example, a resource-adaptor-type-ref must refer to a resource adaptor type that is
already installed in the SLEE. Otherwise, the SBB cannot be installed in the SLEE. The Service Deployer
must set the values of those resource-adaptor-type-ref elements for which no value has been
specified.
6.13.3 Resource adaptor object references

This section describes the programming interfaces and deployment descriptor elements that allow the SBB
code to refer to resource adaptor objects using logical names called resource adaptor entity bindings. A
resource adaptor object is an object that implements the resource adaptor interface of a resource adaptor
type. The resource adaptor entity bindings are special entries in SBB component environments. The Service

Chapter 6
Deployer uses these bindings to bind actual resource adaptor objects provided by resource adaptor entities
at runtime to SBB comp onents.
6.13.3.1 SBB Developer’s responsibilities

This section describes the SBB Developer’s vie w of locating resource adaptor objects and defines the ac-
companying responsibilities.
6.13.3.1.1 Programming interfaces for resource adaptor entity bindings

The SBB Developer must use resource adaptor entity bindings to obtain references to resource adaptor ob-
jects as follows.
• Assign an entry in the SBB’s component environment to the resource adaptor entity binding. (See
Section 6.13.3.1.2 for information on how resource adaptor entity bindings are declared in the
SBB deployment descriptor.)
The SLEE specification recommends, but does not require, that all resource adaptor entity bind-
ings be organized in the subcontexts of the SBB’s component environment, using a different sub-
context for each resource adaptor entity binding under the java:comp/env/slee/re-
sources subcontext . For example, all resource adaptor entity bindings of the JCC resource
adaptor type might be declared in the java:comp/env/slee/resources/jcc subcontext,
and all JAIN SIP resource adaptor entity bindings in the java:comp/env/slee/re-
sources/sip subcontext.
• Lookup the resource adaptor objects in the SBB’s component environment using the JNDI inter-
face.
The following code sample illustrates obtaining a JccProvider object. The JccProvider interface is
the resource adaptor interface of the JCC resource adaptor type.
{
…
JccProvider provider = (JccProvider) new InitialContext().lookup
("java:comp/env/slee/resources/jcc/1.1/jcc_1");
JccCall call = provider.createCall();
…
}
6.13.3.1.2 Declaration of resource adaptor entity bindings in the SBB deploy-

ment descriptor
Although a resource adaptor entity binding is an entry in the SBB’s component environment, the SBB De-
veloper must not use an env-entry element to declare it.
Instead, the SBB Developer must declare all the resource adaptor entity bindings in the SBB deployment
descriptor using resource-adaptor-entity-binding. This allows the SBB Developer and Ser-
vice Deployer to discover all the resource adaptor entity bindings used by an SBB component.
Each resource-adaptor-entity-binding element describes a single resource adaptor entity
binding and is enclosed within a resource-adaptor-type-binding element. The resource-
adaptor-entity-binding element contains the following sub-elements:
• An optional description element.
• A resource-adaptor-object-name element contains the name of the environment entry
used in the SBB component’s code to access the target resource adaptor object of the resource
adaptor entity binding. The name of the environment entry is relative to the java:comp/env
context (e.g., the name should be slee/resources/jcc/… rather than
java:comp/env/slee/resources/jcc/…).

Chapter 6
• A resource-adaptor-entity-link element identifies the resource adaptor entity that

will provide the resource adaptor object that should be bound into the JNDI component environ-
ment of the SBB. The identified resource adaptor entity must be an instance of a resource adaptor
whose resource adaptor type is specified by the resource-adaptor-type-ref sub-element
of the enclosing resource-adaptor-type-binding ele ment.
Each SBB component has its own set of resource adaptor entity binding entries. All instances of classes of
an SBB component share the same resource adaptor entity binding environment entries; the resource adap-
tor entity binding environment entries are not shared with other SBB components. Instances of the classes
of the SBB component are not allowed to modify the SBB component environment at runtime.
The following example is the declaration of resource adaptor entity binding used by the example illustrated
above.
<sbb>
…
…
JCC
javax.csapi.cc.jcc
1.1
…
<resource-adaptor-object-name>
slee/resources/jcc/1.1/jcc_1
</resource-adaptor-object-name>
<resource-adaptor-entity-link>
…
</resource-adaptor-entity-link>
…
</sbb>

The Service Deployer must ensure that the resource-adaptor-entity-link elements of all the
resource-adaptor-entity-binding elements declared by the SBB component are set to mean-
ingful values. A resource-adaptor-entity-link must refer to a resource adaptor entity that is
already instantiated in the SLEE. Otherwise, the SBB cannot be installed in the SLEE. The Service De -
ployer must set the values of those resource-adaptor-entity-link elements for which no value
has been specified.
6.13.4 EJB references

See Section 20.3 in “Enterprise JavaBeans 2.0, Final Release” for a description of the programming inter-
faces and deployment descriptor elements that allow the SBB code to refer to homes of Enterprise Java-
Beans. EJB references are special entries in SBB component environments. The Service Deployer uses
these EJB references to bind EJB homes to SBB comp onents.
6.13.5 The SLEE’s responsibility

The SLEE has the following responsibilities:

Chapter 6
• Implement the java:comp/env environment naming context, and provide it to SBB Objects at
runtime. The naming context must include all the environment entries, resource adaptor type bind-
ings, resource adaptor entity bindings, and EJB references declared by the SBB Developer with
their values supplied (directly or indirectly) by their respective deployment descriptor elements.
The environment naming context must allow creation of subcontexts if they are needed by an
SBB.
• The SLEE must ensure that the instances of the SBB component classes have only read access to
their component environment. The SLEE must throw the javax.naming.OperationNot-
SupportedException from all the methods of the javax.naming.Context interface
that modify the environment naming context and its subcontexts.
6.14 Operations allowed in the methods of the SBB abstract class

Method Method can perform the following operations Transaction
Constructor - Unspecified
setSbbContext JNDI access to java:comp/env Unspecified
unsetSbbContext
sbbActivate
sbbPassivate
initial event selector methods
sbbCreate JNDI access to java:comp/env Mandatory
Resource access
CMP field access
Activity Context attribute access: cannot attach or
detach
Fire events using fire event methods
sbbPostCreate JNDI access to java:comp/env Mandatory
sbbRemove Resource access
sbbLoad CMP field access
sbbStore Activity Context access: includes attributes, attach, and
event handler method detach
local interface method Event mask access
sbbRolledBack Fire events using fire event methods
Create child SBB entities
Invoke methods on SBB local objects
sbbExceptionThrown Same as the method invoked by the SLEE that returned Mandatory
by throwing a RuntimeException.
While changes to transactional state, like creating
child SBB entities, changes to CMP fields, Activity
Contexts, etc, are allowed if the SBB object invoked is
in the Ready state, these changes will be rolled back on
return from an invocation of the sbbException-
Thrown method.
6.15 SBB abstract class methods invoked by the SBB abstract class
Abstract class or interface Method Transaction
SBB abstract class fire event methods Mandatory
get child relation methods
CMP field accessor methods
asSbbActivityContextInterface
get Profile CMP methods

Chapter 6
SbbContext interface getSbbLocalObject Mandatory

getService
getSbb
getActivities
maskEvent Mandatory
getEventMask
setRollbackOnly Mandatory
getRollbackOnly
ChildRelation interface all methods Mandatory
SBB local interface remove Mandatory
isIdentical
getSbbPriority
setSbbPriority
SBB specific local interface methods

Chapter 7
Activity Objects, Activity Contexts, and Activity Context Interface Objects
Chapter 7 Activity Objects, Activity Contexts, and Activity

Context Interface Objects
The SLEE specification specifies the interface of the Java objects used to interact with Activities and Ac-
tivity Contexts as well as the relations among these Java objects, Activities, and other SLEE specification
defined entities.
• Activity.
An Activity represents a related stream of one or more events. These events represent occurrences
of significance that have occurred on the entity represented by the Activity. From a resource’s per-
spective, an Activity represents a state machine within the resource that emits messages or events
on state changes within the resource.
• Activity object.
An Activity object is a Java representation of an Activity. It is an object that provides an Activity
with a visible Java API that can be invoked. Activity objects are defined, created and owned by re-
source adaptor entities or SLEE Facilities.
• Activity Context.
The SLEE uses an Activity Context to represent and encapsulate an underlying Activity object
within the SLEE. An Activity Context holds shareable attributes that SBB entities use to share
state relating to an Activity object and is a logical channel that both emits events and accepts
events fired on the channel. An Activity Context is a logical entity within the SLEE. It does not
have a visible Java API.
• Activity Context Interface object.
An SBB object interacts with an Activity Context through an Activity Context Interface object.
The Activity Context Interface object provides an Activity Context with a visible Java API that
can be invoked. All Activity Context Interface objects implement the generic Activity-
ContextInterface interface and may optionally implement an extended SBB Activity Con-
text Interface interface (see below). The generic ActivityContextInterface interface
does not declare any shareable attributes. There are two kinds of Activity Context Interface ob-
jects.
o Generic Activity Context Interface object.
A generic Activity Context Interface object implements the generic Activity-
ContextInterface interface but does not implement an extended SBB Activity Con-
text Interface interface. It cannot be used to access attributes stored in an Activity Con-
text.
o SBB Activity Context Interface object.
An SBB may define an SBB Activity Context Interface interface that extends the generic
ActivityContextInterface interface. An SBB Activity Context Interface object
implements an SBB Activity Context Interface interface. The SBB Activity Context In -
terface interface declares the shareable attributes of the SBB (see Section 7.4 ). The SBB
Activity Context Interface interface provides a type-safe mechanism for accessing share-
able attributes.
7.1 Relations
The SLEE architecture defines the following relations:
• Activity objects and Activity Contexts: 1-to-1.
• Activity Contexts and Activity Context Interface objects: 1-to-many.
• Activity Contexts and SBB entities: many-to-many.
• Activity Contexts and SLEE Facilities: many-to-many

Chapter 7
7.1.1 Activity objects and Activity Contexts

The following illustration shows the one-to-one relationship between an Activity object and an Activity
Context. Typically, an Activity object resides within the resource domain. An Activity Context resides in
the SLEE domain to represent an underlying Activity object in the resource domain.
SBB
0..n
SBB’s attach to SLEE
Activity Contexts Domain
0..n
Activity Context
The Activity 1
Context provides
access to the
1
Activity Object
Activity Object
The Activity
1 Resource
Object is a Java
representation of Domain
the Activity 1
Activity
Figure 6 Activity objects and Activity Contexts
7.1.2 Activity Contexts and Activity Context Interface objects

The following illustration shows the one-to-many relationship between an Activity Context and Activity
Context Interface objects.
Logically, an Activity Context has a generic Activity Context Interface object and an SBB Activity Context
Interface object for each SBB that defines an SBB Activity Context Interface interface. Each of these SBB
Activity Context Interface objects implements a different SBB Activity Context Interface interface.
generic XSbb - YSbb-

Activity- A c t i v i t y- Activity -
Context- Context- Context -
Interface Interface Interface
object object object
Activity Context
Figure 7 An Activity Context and its Activity Context Interface objects

Chapter 7
7.1.3 Activity Contexts and SBB entities

There is a many-to-many relation between Activity Contexts and SBB entities. SBB entities are attached to
Activity Contexts. The SLEE specification uses the term attachment to refer to this relation.
• Zero or more SBB entities can attach to an Activity Context.
• Each SBB entity can be attached to zero or more Activity Contexts.
• An SBB entity can be attached to a particular Activity Context zero or one times.
• An SBB entity will only receive events fired on Activity Contexts that it has been attached to. The
SLEE automatically attaches an SBB entity to an Activity Context when the SBB entity receives
an initial event delivered on the Activity Context (see Section 8.5). An SBB entity may also e x-
plicitly attach itself to an Activity Context.
• The SLEE automatically detaches an SBB entity from an Activity Context after the SLEE delivers
an Activity End Event to the SBB entity. The SLEE also automatically detaches an SBB entity
from all Activity Contexts before the SBB entity is removed. Alternatively, an SBB entity may
also be explicitly detached from an Activity Context.
7.1.4 Activity Contexts and SLEE Facilities

There is a many-to-many relation between Activity Contexts and SLEE Facilities. The SLEE specification
uses reference to refer to this relationship.
• Each SLEE Facility can reference zero or more Activity Contexts. Examples of SLEE Facilities
that maintain references to Activity Contexts include the Timer Facility and the Activity Context
Naming Facility.
• Each Activity Context can be referenced by zero or more SLEE Facilities.
7.2 Activity object

An Activity object has a Java type of java.lang.Object in the SLEE API. The SLEE specification
does not define a more specific Java type for every Activity object. The SLEE and resource adaptors can
define more specific types for Activity objects. These types are always Objects. For example, the JCC re -
source adaptor type specified JccCall and JccConnection Activity objects. The SLEE and Resource
Adaptor entities can create new Activities.
The SLEE becomes aware of an Activity object in the following ways:
• When an event is fired for the first time on the Activity object.
• When an Activity Context Interface object for interacting with the Activity Context of the A ctivity
object is explicitly requested (see Section 7.6.1).
• When the NullActivityFactory is asked to create a new Activity.
7.2.1 Sources of Activity objects

Main sources of Activity objects include:
• The SLEE.
The SLEE defines the following Activity objects.
o NullActivity – A NullActivity object represents an Activity that has no exter-
nal source of events (see Section 7.10).
o ServiceActivity - The SLEE fires Service lifecycle Events on ServiceActiv-
ity objects (see Section 8.7)
o ProfileTableActivity - The SLEE fires Profile Table and Profile lifecycle events
on ProfileTableActivity objects (see Section 10.3).

Chapter 7
• Resource adaptor entities.

A resource adaptor type declares the Java type of Activity objects common to a set of resource
adaptors. Logically, the resource adaptor entities instantiated from these resource adaptors create
these Activity objects and control the lifetime of these Activity objects. The Java types of these
Activity objects may be defined by the underlying resources represented by the resource adaptor
type. The Java types of Activity objects defined by the underlying resource may include:
o EmergencyReport and CamelReport from JAIN User Location and Status.
o JccConnection and JccCall from Java Call Control.
o Session from JAIN SIPLite.
o ServerTransaction and ClientTransaction from JAIN SIP.
An underlying resource may have a notion of an Activity, but does not use a Java object to repre-
sent this Activity. In this case, the resource adaptor entity that represents the underlying resource
must provide Java objects to represent these Activities. The resource adaptor type of the resource
adaptor entity defines the Java types of these Java objects. For example, JAIN TCAP uses a Dia-
log ID to represent an Activity. The Java type of a Dialog ID is the integer primitive Java type.
The JAIN TCAP resource adaptor type defines java.lang.Integer as the Java type of the
Activity objects that represent Dialog ID Activities.
The source of an Activity object is also the owner of the Activity object since it controls the lifetime of the
Activity object.
7.2.2 Getting an Activity object

There are many ways to obtain a reference to an Activity object. The more common ways include:
• Getting the Activity object from an Activity Context Interface object.
An event handler method is always invoked with an event object and an Activity Context Interface
object. The generic ActivityContextInterface interface imple mented by all Activity
Context Interface objects defines a method that returns an Activity Context Interface object’s un-
derlying Activity object (see Section 7.4).
• Getting the Activity object from an event object.
An event object defines zero or more methods that return Activity objects. For example, a
JccConnectionEvent object (from Java Call Control) has a getCall method to get the
JccCall object and a getConnection method to get the JccConnection object associ-
ated with the JccConnectionEvent object.
• Invoking a resource adaptor entity provided object to create a new A ctivity object.
For example, JccCall (from Java Call Control) defines two methods that create new JccCon-
nection objects: createConnection and routeCall.
• Invoking a NullActivityFactory object to create a new NullActivity object (see Sec-
tion 7.10.2).
• Invoking a ServiceActivityFactory object to obtain a ServiceActivity object (see

Section 8.7.4).
7.2.3 Firing events on an Activity object

The SLEE specification does not define any application visible API for firing an event on an Activity ob-
ject. The SLEE specification does not define any fire event method that takes an Activity object as an ar-
gument.

Chapter 7
The API used internally by the SLEE to fire events on an Activity object and the API used by a resource
adaptor entities to fire an event on an Activity object is outside the scope of this release of the SLEE speci-
fication.
7.2.4 Firing events on an Activity Context

The SLEE specification defines an API that SBBs use to fire events on an Activity Context (see Section
6.1.2).
7.2.5 Every Activity object has an end

Every Activ ity object must have an end. The SLEE specification does not define how an Activity object
ends. Logically, an Activity object ends when no additional events will be emitted from the Activity repre-
sented by the Activity object, except for the last Activity End Event. See Section 7.2.6 for the event type
definition for an Activity End Event.
In most cases, the owner of the Activity object defines what causes the Activity object to end. For example,
a JccCall Activity object may end implicitly when a network event occurs, like a party hanging up. Al-
ternatively, application code may explicitly cause the phone call to end, like invoking the release
method on the JccCall object that represents the phone call (see Section 7.3.4).
When an Activity object ends, the SLEE delivers an Activity End Event to all SBB entities that are attached
to the Activity Context of the Activity object and can receive the Activity End Event (see Section 8.5.5).
7.2.6 Activity End Event

The definition of the Activity End Event is as follows. See Section 8.3.1 for how an event type is defined.
The event-definition element for Activity End Events is as follows:
<event-definition>
…
<event-type-name> javax.slee.ActivityEndEvent </event-type-name>
<event-type-vendor> javax.slee </event-type-vendor>
<event-class-name> javax.slee.ActivityEndEvent </event-class-name>
</event-definition>
The ActivityEndEvent interface is as follows:
package javax.slee;
public interface ActivityEndEvent {

}
7.3 Activity Context

An Activity Context is logical object within the SLEE. It has no visible API. SBB entities interact with
Activity Contexts through Activity Context Interface objects (see Section 7.4). The SLEE uses an Activity
Context to represent and encapsulate an underlying Activity object within the SLEE.
An Activity Context may also hold shareable attributes. Typically, an SBB entity stores information in the
Activity Context to share this information with other SBB entities that are also manipulating the same un-
derlying Activity object. SBB entities should not store per-instance data in Activity Contexts. Per-instance
data should be stored in each SBB entity’s CMP fields (see Section 6.4.3).
Any state stored in an Activity Context by an SBB entity is persistent for the lifetime of the Activity Con-
text. An SBB entity detaching from an Activity Context can expect any information it has stored in the Ac-
tivity Context to be persisted for later use by the same or another SBB entity.

Chapter 7
7.3.1 Activity Context creation

Activity Contexts are created and owned by the SLEE. The SLEE creates a new Activity Context when it is
presented with a new A ctivity object. Typically, this happens when:
• A resource adaptor entity fires an event on an Activity object for the first time.
• An SBB entity invokes an Activity Context Interface Factory object to obtain a generic Activity
Context Interface object for a new Activity object. (The Activity object is probably also created by
the SBB entity).
7.3.2 Activity Context operations

The logical operations that can be performed on an Activity Context include:
• Set and get Activity Context attributes.
Collaborating SBB entities use these attributes to share state that are related to the underlying Ac-
tivity object (see Section 7.4).
• Attach an SBB entity to an Activity Context (see Section 7.4.1) and detach an SBB entity from an
Activity Context (see Section 7.4.3).
• Fire an event on an Activity Context (see Section 8.2.1).
• Deliver an event on an Activity Context (see Section 8.2.2).
• Set and get the event mask of an SBB entity attached to the Activity Context (see Section 8.4.3).
7.3.3 Activity Context state machine

The following diagram illustrates the Activity Context state machine. This state machine allows an Activity
Context to “end gracefully” after the underlying Activity object has ended. It allows the SLEE to deliver
events outstanding on the Activity Context. It also allows SBB entities to receive outstanding events after
the underlying Activity object has ended.

Chapter 7
Active
Activity object of
Activity Context
ends
Ending
No SBB entity attached

to the Activity Context
and no SLEE Facilities
reference the Activity
Context
Invalid
Figure 8 Life cycle of an Activity Context

An Activity Context can be in one of the following three states:
• Active.
The Activity Context has been created. All the Activity Context operations are allowed.
• Ending.
The Activity Context transitions to the Ending state from the Active state when the Activity object
ends. All operations are allowed, except for firing more events on an Activity Context in the End-
ing state. If an SBB entity attempts to fire an event on an Activity Context in the Ending state, the
SLEE will throw a java.lang.Ill egalStateException. While in this state, the SLEE
will continue to deliver outstanding events fired on the Activity Context. After the outstanding
events have been delivered, the SLEE will fire an Activity End Event on the Activity Context. The
SLEE delivers the Activity End Event to each interested SBB entities attached to the Activity
Context and detaches each interested SBB entity from the Activity Context. The SLEE also de-
taches the SBB entities attached to the Activity Co ntext that are not interested in the Activity End
Event.
• Invalid
The Activity Context transitions to the Invalid state from the Ending state when no SBB entity is
attached to the Activity Context (see Section 7.1.3) and no SLEE Facility references the Activity
Context (see Section 7.1.4 ). No operation can be performed on an Activity Context in the Invalid
state. An Activity Context in this state can be garbage collected or reclaimed by the SLEE.
The state of an Activity Context is transactional (see Chapter 9). There is an implicit state variable associ-
ated with each Activity Context that indicates the state of the Activity Context. This state variable can only
be accessed or modified from within transactions. For example, a fire event method reads this implicit state
variable whenever it is called. A fire event method must be invoked with a valid transaction. Alternatively,
this state variable can change asynchronously when an Activity Context ends asynchronously. This asyn-
chronous change must occur within a transaction.

Chapter 7
7.3.4 Activity and Activity Context end examples

This section presents a few examples on how an Activity object ends and how this alters the state of its
associated Activity Context.
7.3.4.1 Explicit ending of a non-transactional Activity object e xample

In this example, an SBB object invokes a method on an Activity object to end the underlying Activity. The
Activity object is a hypothetical non-transactional BazConnection object owned by the BAZ resource
adaptor entity and the end method is close (which is also non-transactional). Invoking this method im-
mediately closes the underlying connection represented by the BazConnection object and no more
events will be emitted by the underlying connection.
1. The SLEE starts a new transaction and invokes an event handler method of an SBB object within
this transaction.
2. The event handler method invokes a BazConnection object’s close method.
3. The BAZ resource adaptor entity closes the underlying connection.
4. The BAZ resource adaptor entity notifies the SLEE that the BazConnection object has ended.
5. The SLEE marks the Activity Context of the BazConnection object as being in the Ending
state. Once the Activity Context is in the ending state the SLEE does not allow additional events
to be fired on the Activity Context.
6. The event handler method returns and the SLEE commits the transaction successfully.
7. Regardless of whether or not the transaction commits, the non-transacted activity will end.The
SLEE continues to deliver any events outstanding on the Activity Context.
8. The last outstanding event on the Activity Context has been delivered.
9. The SLEE performs the two following two sequences concurrently or in an unspecified order:
a. The SLEE fires an Activity End Event on the Activity Context. The SLEE routes the Activity
End Event to each SBB entity that is attached to the Activity Context and is interested in the
Activity End Event (see Section 8.5). After the SLEE delivers the Activity End Event to an
interested SBB entity, the SLEE detach es the SBB entity from the Activity Context .
b. The SLEE also detaches SBB entities that are attached to the Activity Context but are not in-
terested in the Activity End Event.
10. The SLEE notifies the SLEE Facilities that have references to the Activity Context that the Activ-
ity End Event has been delivered on the Activity Context. The Activity Context Naming Facility
will remove the Activity Context’s name bindings. The Timer Facility will remove any timers that
depend on the Activity Context. Both of these Facilities will release their references to the Activity
Context.
11. The SLEE transitions the Activity Context to the Invalid state and the SLEE can reclaim the Ac-
tivity Context.
7.3.4.2 Explicit ending of a transactional Activity object example

In this example, an SBB object invokes a method on an Activity object to end the Activity. The Activity
object is a hypothetical transactional ZaxConnection object owned by the ZAX resource adaptor entity
and the end method is close (which is also transactional). Invoking this method immediately closes the
underlying connection represented by the ZaxConnection object and no more events will be emitted by
the underlying connection.
1. The SLEE starts a new transaction and invokes an event handler method of an SBB object with
this transaction.
2. The event handler method invokes a ZaxConnection object’s close method.

Chapter 7
3. The ZAX resource adaptor entity enrolls the underlying connection in the transaction and marks
the isolated state for the connection as closing. As part of the commit processing the commited
state for the connection is modified to be closing.
4. The event handler method returns and the SLEE commits the current transaction successfully. The
ZAX resource adaptor entity participates in the transaction commit protocol and knows the out-
come of the commit protocol.
If the transaction rolls back, then the ZAX resource adaptor entity would be notified and it will
remove its mark on the underlying connection and will not modify the committed state of the con-
nection.
5. The ZAX resource adaptor entity closes the underlying connection.
6. The ZAX resource adaptor entity notifies the SLEE that the ZaxConnection object has ended.
7. The SLEE marks the Activity Context of the ZaxConnection object as being in the Ending
state.
The remaining steps are the same as steps 7 through 11 in the Section 7.3.4.1.
7.3.4.3 An event ends an Activity object example

In this case, an event fired by a resource adaptor entity ends the Activity object. In this exa mple, a
JccCall object that represents a call ends and an event is fired indicating that no more events will be
fired for the call.
1. The call ends. This call ends either due to:
a. An SBB object ending the call as in the following case:
i. The SLEE starts a new transaction and invokes an event handler method of an
SBB object with this transaction.
ii. The event handler method invokes a JccCall object’s release method.
iii. The event handler method returns and the SLEE commits the current transaction
successfully.
As the JCC resource is not a transactional resource the call will be released whether or
not the transaction commits or is rolled back.
b. One of the parties on a two party call hangs up.
2. The JCC resource adaptor entity releases the underlying call.
3. The JCC resource adaptor entity emits a JccCallEvent object whose getCause method re-
turns JccCallEvent.CALL_EVENT_TRANSMISSION_ENDED.
4. The JCC resource adaptor entity notifies the SLEE that the JccCall object has ended.
5. The SLEE marks the Activity Context of the JccCall object as being in the Ending state.
The remaining steps are the same as steps 7 through 11 in the Section 7.3.4.1.
7.4 Generic ActivityContextInterface interface

All Activity Context Interface objects implement the generic ActivityContextInterface interface.
The ActivityContextInterface interface is:
package javax.slee;
public interface ActivityContextInterface {

public Object getActivity()
SLEEException;
public void attach(SbbLocalObject sbbLocalObject)
throws NullPointerException,

Chapter 7
TransactionRolledbackLocalException,
SLEEException;
public void detach(SbbLocalObject sbbLocalObject)
SLEEException;
public boolean isEnding()
SLEEException;
}
All the methods of the ActivityContextInterface interface are mandatory transactional methods
7.4.1 ActivityContextInterface interface getActivity method

The ActivityContextInterface interface has a getActivity method. This method returns the
Activity object of an Activity Context.
• It is a mandatory transactional method (see Sectio n 9.6.1). It throws a javax.slee.Trans-
actionRequiredLocalException if it is invoked without a valid transaction context.
7.4.2 ActivityContextInterface interface attach method

The ActivityContextInterface interface has an attach method. This method attaches the SBB
entity represented by the SBB local object specified by the sbbLocalObject argument to an Activity
Context so that the specified SBB entity can receive events fired on the Activity Context.
• The sbbLocalObject argument must represent a valid SBB entity when this method is in-
voked. Otherwise, this method marks the current transaction for rollback and throws a java-
x.slee.TransactionRolledbackLocalException.
• This method throws a java.lang.NullPointerException if the sbbLocalObject
argument is null.
• This method does not change the values of any Activity Context attributes.
• This method attaches the SBB entity specified by the sbbLocalObject argument to the Activ-
ity Context. An SBB that is attached to an Activity Context is eligible to receive events fired on
the Activity Context.
• This method also sets the event mask of the specified SBB entity for the Activity Context to the
set of event types whose mask-on-attach attribute of their event elements within the sbb
element of the specified SBB is true (see Section 8.3.2).
• It is a mandatory transactional method (see Section 9.6.1). It throws a javax.slee.Trans-
• It throws a javax.slee.SLEEException if the SBB entity cannot be attached due to a sys-
tem-level failure.
See Section B.2 for the pseudo code that illustrates the desired behavior of the attach method.
This method should not be used to attach an SBB entity to the Activity Context of the Activity Context Inter-
face object passed to the SBB entity through an event handler method since the SBB entity must already be
attached to this Activity Context, in order for the SBB entity to receive an event through the event handler
method (see Section 8.5).

Chapter 7
7.4.3 ActivityContextInterface interface detach method

The ActivityContextInterface interface has a detach method. This method detaches the SBB
entity represented by the SBB local object specified by the sbbLocalObject argument from an Activity
Context so that the specified SBB entity will no longer receive events fired on the Activity Context.
• The sbbLocalObject argument must represent a valid SBB entity when this method is in-
voked. Otherwise, this method marks the current transaction for rollback and throws a
javax.slee.TransactionRolledbackLocalException.
• This method throws a java.lang.NullPointerException if the sbbLocalObject
argument is null.
• This method detaches the SBB entity specified by the sbbLocalObject argument from the Ac-
tivity Context.
actionRequiredLocalException if it is invoke d without a valid transaction context.
• It throws a javax.slee.SLEEException if the SBB entity cannot be detached due to a sys-
tem-level failure.
See Section B.3 for the pseudo code that illustrates the desired behavior of the detach method.
7.4.4 ActivityContextInterface interface isEnding method

The ActivityContextInterface interface has an isEnding method. This method returns whether
the Activity Context is in the Ending state.

Chapter 7
7.5 SBB Activity Context Interface interface

An SBB may define an SBB Activity Context Interface interface that extends, either directly or indirectly,
the generic ActivityContextInterface interface to declare the shareable attributes of the SBB.
Every shareable attribute has an attribute name. The SLEE generates the concrete class that implements the
SBB Activity Context Interface interface when the SBB is deployed into the SLEE as a part of a deployable
unit.
XSbb YSbb YSbb ZSbb

SBB entity SBB entity SBB entity SBB entity
X1 Y1 Y2 Z2
Use Use Use Use
XSbb- YSbb- ZSbb-

Activity- Activity- Activity-
Context - Context- Context-
Interface Interface Interface
object object object
attrs x1,x2, attrs y1,y2, attrs z1,z2,

... ...
Provides
...
Provides Provides
interface to
interface to interface to
Activity Context
contains attrs
x1, x2, ...
y1, y2, ...
z1, z2, ...
Represents
Activity object
Figure 9 SBB Activity Context Interface objects example

If an SBB does not define an SBB-specific SBB Activity Context Interface interface, the SBB uses the ge-
neric ActivityContextInterface interface. Since the generic ActivityContextInterface
interface does not declare any shareable attributes, this SBB will not be able to get or mo dify any attributes
in any Activity Contexts.
The SBB Activity Context Interface interface must be public.

Chapter 7
7.5.1 SBB Activity Context Interface get and set accessor methods
The SBB Developer must declare a set accessor method and/or a get accessor method for each shareable
attribute in the SBB Activity Context Interface interface.
• The rules for computing accessor method names from an attribute name are the same as the rules
for computing accessor method names from a CMP field name (see Section 6.5.1).
• The Java types of an Activity Context attribute are restricted to Java primitive types and Java seri-
alizable types. SBB local interfaces (i.e., SbbLocalObject and the types d erived from
SbbLocalObject) cannot be stored in Activity Context attributes.
• The semantics of these accessor methods are also the same as the semantics of CMP field accessor
methods.
• For an attribute to be writeable, the SBB Developer must define a set accessor method. For an at-
tribute to be readable, the SBB Developer must define a get accessor method. An attribute can be
(from the SBB’s point of view), either read-only, write-only or read-write, based on the methods
defined.
• Activity Context attribute accessor methods are mandatory transactional methods (see Section
9.6.1).
In the following example, the FooSbbActivityContextInterface interface declares two attrib-
utes.
…
…
public interface FooSbbActivityContextInterface extends ActivityContextInterface {
public int getFooAmount();
public void setFooAmount(int fooAmount);
public String getTestString();
public void setTestString(String testString);
}
7.6 Getting an Activity Context Interface object

There are several ways for an SBB object executing on behalf of an SBB entity to obtain a reference to an
Activity Context Interface object. The most common ways include:
• The SBB abstract class has an event handler method. When the SLEE delivers an event to the
SBB entity, the SLEE invokes the event handler method, passing to the event handler method an
event object and an Activity Context Interface object (see Section 8.4.2).
• The SBB object invokes an Activity Context Interface Factory object to get a generic Activity
Context Interface object from an Activity object.
• The SBB retrieves a generic Activity Context Interface object from the Activity Context Na ming
Facility (see Section 7.9).
7.6.1 Activity Context Interface Factory objects

Every Activity object source has an Activity Context Interface Factory object. The Activity Context Inter-
face Factory object has factory methods. Each factory method “manufactures” generic Activity Context
Interface objects from Activity objects of a specific type defined by the Activity object source.
For example, the JccActivityContextInterfaceFactory interface for Java Call Control may
look like this:
…
import javax.slee.FactoryException;
import javax.slee.UnrecognizedActivityException;
import javax.slee.TransactionRequiredLocalException;
…

Chapter 7
public interface JccActivityContextInterfaceFactory {
public ActivityContextInterface
getActivityContextInterface(JccCall call)
UnrecognizedActivityException,
FactoryException;
getActivityContextInterface(JccConnection connection)
FactoryException;
}
• All factory methods are mandatory transactional methods.

• The SLEE specification defined NullActivityContextInterfaceFactory can be found
in Section 7.10.
• The SLEE specification defined ServiceActivityContextInterfaceFactory can be
found in Section 8.7.5.
• The SLEE specification defined Activity Context Interface Factory objects are bound to well-
defined locations in every SBB component environment.
• An SBB binds resource adaptor type defined Activity Context Interface Factory objects into its
component environment using resource-adaptor-type-binding elements in the SBB’s
deployment d escriptors (see Section 6.13.2).
A factory method may throw the following exceptions:
• java.lang.NullPointerException.
A factory method throws this exception if any of its arguments are null.
• javax.slee.UnrecognizedActivityException.
A factory method throws this exception when the input argument does not represent an valid Ac-
tivity for this Activity Context Interface Factory object, e.g. the Activity object is from a resource
adaptor entity not served by this Activity Context Interface Factory object.
• javax.slee.TransactionRequiredLocalException.
A factory method is a mandatory transactional methods (see Section 9.6.1). It throws a ja-
vax.slee.TransactionRequiredLocalException if it is invoked without a valid
transaction context.
• javax.slee.FactoryException.
A factory method throws this exception if the method cannot create or return an ActivityCon-
textInterface object because of system-level or SLEE-level problems. This exception is de-
rived from javax.slee.SLEEException.
7.7 Activity Context methods in SBB abstract class and SbbContext

An SBB object uses the following methods provided in the SbbContext interface to interact with Activ-
ity Contexts.
• A getActivities method to get all the Activity Contexts attached to the SBB entity assigned
to the SBB object.
• A maskEvent method specifies a set of event types that an SBB entity assigned to the SBB ob-
ject does not want to receive from a specific Activity Context (see Section 8.4.3.1).
• A getEventMask method to obtain the set of event types that an SBB entity assigned to the
SBB object does not want to receive from a specific Activity Context (see Section 8.4.3.2).

Chapter 7
An SBB object uses the following method declared by the SBB Developer in the SBB abstract class to in-
teract with Activity Contexts.
• An asSbbActivityContextInterface method to narrow an object that implements the
generic ActivityContextInterface interface to an object that implements the SBB-
specific SBB Activity Context Interface interface.
7.7.1 SbbContext interface getActivities method

The SbbContext object of every SBB object has a getActivities abstract method. An SBB object
assigned to an SBB entity uses this method to get all the Activity Contexts that SBB entity is attached to.
The getActivities method looks like this:
public interface SbbContext {
…
public ActivityContextInterface[] getActivities()
SLEEException;
…
}
See Section B.4 for the pseudo code that illustrates the desired behavior of the getActivities method.
7.7.2 SBB abstract class asSbbActivityContextInterface method

The SBB abstract class of an SBB that defines an SBB Activity Context Interface interface must declare an
asSbbActivityContextInterface method.
This method takes as its input parameter an Activity Context Interface object and returns an object that
implements the SBB Activity Context Interface interface of the SBB. The SBB Activity Context Interface
interface provides the accessor methods that allow an SBB object to access the shareable attributes of the
SBB that are stored in the Activity Context.
If the SBB does not define an SBB Activity Context Interface interface, then this method cannot be de-
clared in the SBB abstract class.
The method signature of this method is as follows:
public abstract <SBB Activity Context Interface>
asSbbActivityContextInterface(ActivityContextInterface activity);
plementation of the method when the SBB is deployed.
• The return type must be the Activity Context Interface interface of the SBB, or a base interface of
the Activity Context Inteface interface of the SBB.
• This method does not have throws clause.
• The SBB object must have an assigned SBB entity when it invokes this method. Otherwis e, this

Chapter 7
7.8 Activity Context attribute aliasing

By default, the Activity Context attributes defined in the SBB Activity Context Interface interface of an
SBB are not accessible by other SBBs. The attributes that an SBB entity stores in an Activity Context can
only be accessed by SBB entities of the same SBB9 because SBB entities of the same SBB use the same
SBB Activity Context Interface object to interact with the Activity Context. This avoids unintentional
shared access to the same attribute when composing SBBs, or when deploying Services from different
sources.
Activity Context attribute aliasing directs the SLEE to make the attributes declared in different SBB Activ-
ity Context Interface interfaces behave logically as a single attribute. This logical attribute has a name
known as the alias name. The logical attribute can be updated through any of its aliased attributes’ set ac-
cessor methods. Changes to the logical attribute are observable through any of these attributes’ get accessor
methods. Shareable attributes defined in an SBB Activity Context Interface interface of an SBB are not
“shared” with other SBBs unless explicitly aliased.
• The attributes that are to be aliased must be of the same Java type.
• An SBB Activity Context Interface attribute may be aliased at most once, i.e. it can either be una-
liased or aliased through a single alias name.
7.8.1 Activity Context attribute aliasing deployment descriptor elements

The SBB Developer or Service Deployer specifies an Activity Context attribute alias using deployment
descriptor elements in the sbb deployment descriptor element. Each Activity Context attribute alias is rep-
resented by an activity-context-attribute-alias element. An activity-context-
attribute-alias element is a sub-element of the sbb element. See Section 3.1.8 for a description of
the activity-context-attribute-alias element.
7.8.2 Activity Context attribute aliasing example

The following SBB deployment descriptor example aliases the blockCounter Activity Context attribute
of the CallBlocking SBB and the forwardCounter Activity Context attribute of the CallForwarding
SBB, and names the aliased logical attribute counter.
<sbb>
…
<sbb-name> CallBlockingSbb </sbb-name>
…
<activity-context-attribute-alias>
<attribute-alias-name>
counter
</attribute-alias-name>
<sbb-activity-context-attribute-name>
blockCounter
</sbb-activity-context-attribute-name>
</activity-context-attribute-alias>
…
</sbb>
9
The SBB entities of the same SBB are the SBB entities that are instantiated from a single SBB component (which is installed in the
SLEE only once) regardless of which Service the SBB entities are instantiated for.
Chapter 7
…
<sbb>
…
<sbb-name> CallForwardingSbb </sbb-name>
…
<activity-context-attribute-alias>
<attribute-alias-name>
counter
</attribute-alias-name>
<sbb-activity-context-attribute-name>
forwardCounter
</sbb-activity-context-attribute-name>
</activity-context-attribute-alias>
…
</sbb>
7.9 Activity Context Naming Facility

A SLEE specification defined Activity Context Naming Facility provides a global flat namespace for nam-
ing Activity Contexts. It has methods to:
• Bind a name to an Activity Context.
This operation causes the Activity Context Naming Facility to reference the Activity Context (see
Section 7.1.4). A Null Activity can not implicitly transition from the Active to the Ending state,
and can not be reclaimed while the Activity Context for the Null Activity is referenced by the Ac-
tivity Context Naming Facility.
• Find an Activity Context by name.
• Unbind an Activity Context entity from its name binding.

This operation causes the Activity Context Naming Facility to not reference the Activity Context.
The Activity Context Naming Facility is used as follows:
• SBB objects use JNDI lookup to obtain an ActivityContextNamingFacility object from
a SLEE specification defined location in every SBB component environment (see Section 6.13).
• The SBB Developers that use this Facility are responsible for choosing unique names to avoid un-
intentional naming conflicts.
• This Facility allows multiple SBB entities that have been created in response to initial events on
different Activities (thus have d ifferent Activity Contexts) to converge on a “shared” Activity
Context, so that these SBB entities can signal each other by firing events on the shared Activity
Context and share common state by reading and modifying attributes.
7.9.1 Activity Context Naming Facility and Activity End Events

The Activity Context Naming Facility assists Activity Context reclamation by automatically unbinding an
Activity Context from its name binding after the SLEE has delivered an Activity End Event to all SBB en-
tities that are attached to the Activity Context and can receive the Activity End Event (see Section 8.5.5).
7.10 NullActivity objects

NullActivity objects do not process events from external resources. They are created and used by ap-
plications, and garbage collected by the SLEE. The only event which the SLEE fires on a NullActivity
object is the ActivityEndEvent. SBBs may fire events on the Activity Context of a NullActivity ob-
ject.

Chapter 7
Collaborating SBB entities can use the Activity Context of a NullActivity object as a private commu-
nications channel. They signal one another by firing events on the Activity Context of the NullActiv-
ity object and store shareable attributes in the Activity Context of the NullActivity object.
The SLEE makes a NullActivityFactory object accessible via an SBBs component environment.
The NullActivityFactory object creates NullActivity objects. Hence, the SLEE is the owner of
all NullActivity objects.
7.10.1 NullActivity interface

The SLEE specification defines NullActivity as a Java interface that contains a single endActiv-
ity method.
package javax.slee.nullactivity;
import javax.slee.SLEEException;
public interface NullActivity {

public void endActivity() throws TransactionRequiredLocalException, SLEEException;
}
• If the NullActivity object is already ending, subsequent endActivity method invocations
are ignored.
ee.TransactionRequiredException if it is invoked without a valid transaction context.
• This method throws a javax.slee.SLEEException if the requested operation cannot be
completed because of a system-level failure.
7.10.2 NullActivityFactory interface

The SLEE specification defines the NullActivityFactory as a Java interface that contains a single
createNullActivity method. The NullActivityFactory object is bound to a SLEE specifica-
tion defined location in the component environment of every SBB (see Section 7.10.6).
public interface NullActivityFactory {

public NullActivity createNullActivity()
throws TransactionRequiredLocalException, FactoryException;
}
• This method throws a javax.slee.FactoryException if the method cannot create or re-
turn a NullActivity object because of system-level or SLEE-level problems. This exception is
derived from javax.slee.SLEEException.
7.10.3 NullActivityContextInterfaceFactory interface

An SBB can obtain a generic Activity Context Interface object for a NullActivity object using a Nul-
lActivityContextInterfaceFactory object. The NullActivityContextInterface-
Factory object is also bound to a SLEE specification defined location in the component environment of
every SBB.

Chapter 7
public interface NullActivityContextInterfaceFactory {

getActivityContextInterface(NullActivity activity)
FactoryException;
}
• See Section 7.6.1 for a general description on Activity Context Interface Factories, the transac-
tional semantics, and the exceptions thrown by a getActivityContextInterface method.
7.10.4 All NullActivity methods are transactional

All the methods of the NullActivity interface, NullActivityFactory interface, and the Nul-
lActivityContextInterfaceFactory interface are mandatory transactional methods (see Section
9.6.1). For example, this means that a NullActivity object ends only if the transaction that invoked the
endActivity method commits succes sfully.
7.10.5 Ending a NullActivity object

A NullActivity object may end either implicitly or explicitly. In b oth cases, the processing that occurs
after the NullActivity object ends is the same as for all other Activity objects when they end. This
processing is described in Section 7.3.3.
7.10.5.1 Implicitly ending a NullActivity object

The condition that implicitly ends a NullActivity object is as follows:
• No SBB entities are attached to the Activity Context of the NullActivity object, and
• No SLEE Facilities reference the Activity Context of the NullActivity object, and
• No events remain to be delivered on the Activity Context of the NullActivity object.
All methods that may change the attachments or references of an Activity Context are mandatory transac-
tional. Hence, if an SBB method invocation changes an Activity Context’s attachments and references, it
must do so within a transaction. Therefore, when the transaction commits, the SLEE only has to examine
the NullActivity objects whose Activity Contexts were enrolled in the transaction to determine which
NullActivity objects should end.
For example, an SBB object creates a new NullActivity object within a transaction since the cre-
ateNullActivity method of the NullActivityFactory interface is a mandatory transactional
method (see Section 7.10.2). If the SBB object does not attach its assigned SBB entity to the Activity Con-
text of the new NullActivity object or bind a name to the Activity Context of the new NullActiv-
ity object using the Activity Context Naming Facility, then when the transaction commits, the SLEE will
end the new NullActivity object because the Activity Context of the NullActivity object will
have no attachments and references. If the transaction rolls back, then the end result should be the same as
if the NullActivity object was not created.
A possible sequence of events and invocations for this example follows:
this transaction.
2. The event handler method creates a new NullActivity object by invoking a NullActiv-
ityFactory object’s createNullActivity method.

Chapter 7
This enrolls the NullActivity object in the current transaction.
The following sequence would also be the same if the event handler method detaches the only SBB
entity attached to a NullActivity object’s Activity Context and this Activity is not referenced
by any SLEE Facilities.
3. The event handler method returns and the SLEE commits the current transaction successfully.
4. The SLEE determines that the NullActivity is not attached to any SBB entity and is not ref-
erenced by any SLEE Facility. It ends the NullActivity object.
The NullActivity object may perform this determination. For example, the transaction coor-
dinator may notify the NullActivity object that the transaction has committed by invoking a
callback method on the NullActivity object. This callback method determines if the Nul-
lActivity object remains attached to at least one SBB entity or remains refe renced by at least
one SLEE Facility.
5. The SLEE continues to deliver any event outstanding on the Activity Context.
At this point, the Activity Context is in the Ending state and the SLEE does not allow additional
events to be fired on the Activity Context.
While the SLEE is delivering events outstanding on the Activity Context, the SLEE may instantiate
new root SBB entities to receive outstanding initial events and attach these new SBB entities to the
Activity Context. Alternatively, SBB objects may also instantiate new child SBB entities, and at-
tach these new SBB entities to the Activity Context in the Ending state to receive events out-
standing on the Activity Context. The SLEE will eventually forcefully detach these newly attached
SBB entities from the Activity Context.
6. The last outstanding event on the Activity Context has been delivered. The SLEE fires an Activity
End Event on the Activity Context.
7. The SLEE performs the two following sequences concurrently or in an unspecified order:
a. The SLEE delivers the Activity End Event to each SBB entity that is attached to the Activity
Context and is interested in the Activity End Event (see Section 8.5.5). After the SLEE deliv-
ers the Activity End Event to the interested SBB entity, it detaches the interested SBB entity
from the Activity Context.
b. The SLEE detaches the SBB entities that are attached to the Activity Context and are not in-
terested in the Activity End Event.
tivity Context.
7.10.5.2 Explicitly ending a NullActivity object

An SBB object can also explicitly end a NullActivity object by invoking the NullActivity ob-
ject’s endActivity method. When the transaction in which the endActivity method was invoked
commits, the NullActivity object ends.
A possible sequence of events and invocations for this example follows:
this transaction.
2. The event handler method ends a NullActivity object by invoking its endActivity
method.
3. The NullActivity object notifies the SLEE that the NullActivity object has ended.
4. The SLEE marks the Activity Context of the NullActivity object as being in the Ending state.
5. The event handler method returns and the SLEE commits the current transaction successfully.
If the transaction rolls back, then the NullActivity object will not end and the SLEE does not
mark the Activity Context as being in the Ending state.
Chapter 7
6. The SLEE continues to deliver any event outstanding on the Activity Context.
At this point, the SLEE does not allow additional events to be fired on the Activity Co ntext.
7. The last outstanding event on the Activity Context has been delivered. The SLEE fires an Activity
End Event on the Activity Context.
8. The SLEE performs the two following sequences concurrently or in an unspecified order:
a. The SLEE delivers the Activity End Event to each SBB entity that is attached to the Ac-
tivity Context and is interested in the Activity End Event (see Section 8.5.5). After the
SLEE delivers the Activity End Event to the interested SBB entity, it detaches the inter-
ested SBB entity from the Activity Context.
b. The SLEE detaches the SBB entities that are attached to the Activity Context and are not
interested in the Activity End Event.
9. The SLEE notifies SLEE Facilities that have references to the Activity Context that the Activity
End Event has been delivered on the Activity Context. The Activity Context Naming Facility will
remove the Activity Context’s name bindings. The Timer Facility will remove any timers that de-
pend on the Activity Context. Both of these Facilities will release their references to the Activity
Context.
tivity Context and the NullActivity object.
7.10.6 JNDI names of NullActivity related objects

The following table lists the names of the SLEE specification defined names for NullActivity related
objects under java:comp/env.
Objects Names
NullActivityFactory object slee/nullactivity/factory
NullActivityContextInterfaceFactory slee/nullactivity/activitycontextinterfacefactory
object
7.11 Activity Context and Activity object persistence

All Activity Contexts are persistent. They have persistent state, i.e. Activity Context attributes, associated
with them and they survive SLEE restarts. Their attachment (applies to SBB entities) and reference (applies
to SLEE Facilities) relations are also persistent. However, the Activity object of the Activity Context may
not be persistent. For example, a TCP connection will not survive a SLEE restart. The SLEE together with
the resource adaptor entity that owns the Activity object is responsible for ending the Activity object if the
Activity object does not surv ive a restart.
All SLEE specification defined Activity objects are persistent. These Activity objects include Null-
Activity, ProfileTableActivity (see Section 10.3.1), and ServiceActivity (see Section
8.7.11.1) objects.

Chapter 8
Events
Chapter 8 Events
Events represent occurrences of significance or state transitions within the SLEE or outside the SLEE.
They are used to convey information about the occurrence from one entity in the SLEE to another entity in
the SLEE. These entities may be the SLEE, SBB objects, resource adaptor entities that represent external
resources, and SLEE Facilities.
For example, the SLEE fires an Activity End Event on an Activity Context when the Activity Context’s
Activity object ends.
For communication among SBB entities, SBB entities should use events to signal each other and use Activ-
ity Contexts to share common s tate. This reduces the use of direct references among SBB entities and ref-
erences to SBB entities by other entities.
8.1 Overview
Event producers fire events. Event consumers receive events. The SLEE event router delivers events fired
by event producers to event consumers.
Each event fired by an event producer is represented within the SLEE by:
• An event object (see Section 8.1.5).
• An event type (see Section 8.1.7).
8.1.1 Event producers

Event producers include:
• Resource adaptor entities.
Events fired by resource adaptor entities are also known as resource events.
• The SLEE.
Events fired by the SLEE are known as SLEE events. The event types fired by the SLEE include
the Activity End Event, the Profile Added Event, the Profile Removed Event and the Profile Up-
dated Event, and Service Lifecycle related Events .
• SLEE Facilities.
Events fired by SLEE Facilities are known as SLEE Facility events. For exa mple, the SLEE Timer
Facility fires Timer Events.
• SBB objects.
SBB objects that have been assigned to SBB entities may fire events.
8.1.2 Event consumers

The only event consumers defined by the SLEE specification are SBB entities. The SLEE specification
defines how events are delivered to SBB entities.
8.1.3 SBB as an event producer and fire event methods

Each SBB that fires events must declare the event types that it fires. For each event type that the SBB fires,
the SBB Developer declares an abstract fire event method in the SBB abstract class. The abstract fire event
method is implemented by the SLEE when the SBB is installed into the SLEE as part of a deployment unit.
An SBB object invokes a fire event method to hand an event that it would like to fire to the SLEE event
router. The event name binding for the event type that the fire event method fires determines the name of
the fire event method (see Section 8.4.1).

Chapter 8
Events
8.1.4 SBB as an event consumer and event handler methods

Each SBB that receives events must declare the event types that it receives. For each event type that the
SBB receives, the SBB defines and implements an event handler method in its SBB abstract class. This
event handler method contains application logic to process events of the event type.
The SLEE event router invokes an event handler method of an SBB object to hand an event to the SBB
object for processing. The event name binding for the event type that the event handler method receives
determines the name of the event handler method (see Section 8.4.2).
8.1.5 Event object

An event object is the Java object that represents the event and carries the information to be conveyed. For
example, an ActivityEndEvent object represents an Activity End Event. An event object must be a
java.lang.Object, i.e. it cannot be a primitive type.
8.1.6 Event class

The publicly declared Java class or interface of an event object is known as the event class. For example,
the event class of a Timer Event is the TimerEvent interface, and not the concrete implementation class
of this interface.
8.1.7 Event type

When an event producer fires an event, it must provide to the SLEE the event type of the event. The event
type of the event completely determines how the SLEE will route the event, i.e. which SBB entities will
receive the event, and which event handler method will be invoked to process the event.
The event type of an event is independent of its event class. The event producer defines the event types that
it can fire in a deployment descriptor element. The event producer documentation, specification and de-
ployment descriptor elements are expected to contain descriptive text that specifies how the event producer
maps the events that the event producer fires to different event types.
For example, the Java Call Control specification defines the JccCallEvent event class and the
JccConnectionEvent event class. Both JccCallEvent and JccConnectionEvent have a
cause code indicating the cause of the event. It is desirable to define a different event handler method for
each event cause code, rather than a different event handler for each event class. This allows the SBB De-
veloper finer control over the event causes that an SBB would like to process. For e xample, the SBB could
choose to process Connection Alerting Events but not Connection Connected Events. To allow this fine
grain control over event routing, the Java Call Control resource adaptor type should provide a unique event
type for each cause code, i.e. all events with the same cause code belong to the same event type.
In the case of the JAIN User Location and Status resource adaptor type, providing an event type for each
event class defined by the JAIN User Location and Status specification would be very appropriate. Each of
the following event classes defined in the JAIN User Location and Status specification should have its own
event type: CamelReportResultEvent, CamelReportErrorEvent, EmergencyReportRe-
sultEvent, EmergencyReportErrorEvent, ExtendedReportErrorEvent, ExtendedRe-
portResultEvent, PeriodicCamelReportResultEvent, PeriodicCamelReportError-
Event, PeriodicCamelReportStoppedEvent, PeriodicReportResultEvent, Periodi-
cReportErrorEvent, PeriodicReportStoppedEvent, ReportResultEvent, ReportEr-
rorEvent, StatusReportResultEvent, StatusReportErrorEvent, Subscription-
ResultEvent, SubscriptionStoppedEvent, TriggeredCamelReportErrorEvent,
TriggeredCamelReportResultEvent, TriggeredCamelReportStoppedEvent, Trig-
geredReportResultEvent, TriggeredReportErrorEvent, TriggeredReport-
StoppedEvent, TriggeredStatusReportResultEvent, TriggeredStatusReportEr-
rorEvent, TriggeredStatusReportStoppedEvent.

Chapter 8
Events
When an event producer fires an event, it provides to the SLEE the event type of the event either directly or
indirectly (see Section 8.2.1). The SLEE does not inspect the event object or the Activity object on which
the event was fired to determine the event type of the event.
The SLEE specification does not define any application code visible API for event type. SBB components
cannot define methods with event type arguments and cannot invoke methods with event type arguments.
The human readable representation of an event type is composed of three strings containing the event
type’s name, vendor and version. Hence, an event type identifier consists of the event type’s name, vendor
and version. This representation of the event type is used in deployment descriptor elements. It is recom-
mended that the SBB Developers should adopt the fully qualified Java package naming convention for
event type names.
8.1.8 Custom event types

Custom event types are event types introduced by SBB Developers.
The primary difference between a custom event object and a non-custom event object is that custom event
objects are created by SBB objects while non-custom event objects are created by other event producers.
All custom event objects must:
• Be serializable.
The event class of a custom event type must specify either a Java class or interface that is serializ-
able. This restriction allows a distributed SLEE implementation to distribute the custom event ob-
jects to multiple Java Virtual Machines.
• Implement hashCode.
The actual implementation class of a custom event object must override the Object.hashCode
method. The new hashCode method does not need to provide has h codes that are unique but
does need to provide hash codes that are well distributed. A well-distributed hash code algorithm
reduces but does not eliminate the number of times different custom event objects evaluate to the
same hash code. When different custom event objects evaluate to the same hash code they are
stored together and uniquely identified by their equals method. The custom event object over-
rides the hashCode method for the benefit of hash tables such as those provided by
java.util.Hashtable. See java.lang.Object for more information.
• Implement equals.
The actual implementation class of a custom event object must override the Object.equals
method. The new equals method must ensure that the implementation of the method is refle x-
ive, symmetric, transitive and for any non-null value X, X.equals(null) returns false. See
java.lang.Object for more information.
8.1.9 Non-custom event types

Requirements and restrictions on non-custom event objects are outside the scope of the SLEE specification.
• Since the SLEE event objects and SLEE Facility event objects are created by the SLEE, these
event objects already conform to the SLEE require ments for non-custom event objects.
• As for event objects produced by resource adaptor entities, these event objects must conform to
the requirements of the individual SLEE implementations. The current SLEE specification does
not fully specify these requirements. The SLEE vendor is expected to specify these requirements
as part of the vendor specific documentation.
A future version of the SLEE specification is expected to define standard resource adaptor inter-
faces and requirements.

Chapter 8
Events
8.1.10 Event name

Within an SBB, the SBB refers to an event type by an event name. An event name is an SBB scoped local
name that refers to an event type. This name must conform to the naming requirements of Java method
names.
• The event name of an event type determines the name of the event handler method that receives
events of the event type or the name of the fire event method used to fire events of the event type.
• An SBB uses the event name of an event type to identify the event types that should be masked
8.2 Events and Activity Contexts

There are two important relationships between events and Activity Contexts. The two main relationships
are:
• An event producer always fires an event on an Activity Context and an optional default address.
The event producer adds an event to the event stream represented by the Activity Context. When
doing so, the event producer provides the event (consisting of the event object and event type), the
Activity Context on which the event is fired on, and an optional default address.
• An SBB entity always receives an event on an Activity Context.
The SBB entity receives an event from the event stream represented by the Activity Context. An
SBB entity will only receive events on an Activity Context that it is attached to. The SLEE will
not deliver an event fired on an Activity Context to an SBB entity that is not attached to the Activ-
ity Context. In the case of an initial event, the SLEE will attach the SBB entity to the Activity
Context before delivering the initial event to the SBB entity (see Se ction 8.5).
8.2.1 Firing an event on an Activity Context and a default address

When an event producer fires an event, it must provide to the SLEE, either directly or indirectly, three
pieces of information.
• The event.
This includes the Java event object and the event type. Typically, a resource adaptor entity pro-
vides an event type directly when it passes the event to the SLEE (see Section 15.7), and an SBB
object indirectly identifies the event type through the fire event method used to fire the event (see
Section 8.4.1).
• The Activity Context that the event is fired on.
The event producer identifies an Activity Context using one of the Activity Context’s visible Java
objects, i.e. an Activity object or an Activity Context Interface object (see Section 7.4 ). In most
cases, a resource adaptor entity will identify an Activity Context by an Activity object and an SBB
object will identify an Activity Context by an Activity Context Interface object.
• An optional default address.
The event producer may provide an optional default address. The default address is used to sup-
port certain standard initial event policies built into the SLEE (see Section 8.5). An event being
fired by an event producer may have one or more addresses associated with it. These addresses
may be obtained from the event object or from the Activity object. The event producer may pro-
vide one of these addresses as the default address.
In general, the default address is obtained from an event class attribute or an Activity class attrib-
ute for all events of the same event class. A well-specified resource adaptor type should always
identify the attribute that provides the default address for each event type that its resource adaptor
entities fire.
If the event type of the event is an initial event type of a Service and the initial event policy for the
event type is a built -in policy that uses the default address, the SLEE event router uses the default

Chapter 8
Events
address together with the Address Profile Table of the Service (see Section 10.13.2) to determine
whether a new root SBB entity of the Service should be instantiated to process the event. If a new
root SBB entity is instantiated, this event is the new SBB entity’s initial event (see Section 8.5.1).
8.2.2 Receiving an event on an Activity Context

An SBB entity receives an event through one of its event handler methods (see Section 8.4.2). When the
SLEE delivers an event to an SBB entity, it invokes the event handler method for the event’s event type on
an SBB object that is assigned to the SBB entity. The SLEE passes the following pieces of information to
the event handler method:
• The event.
The SLEE passes the event object (or a copy of the event object) handed to it by the event pro-
ducer to the event handler method. The event type of the event determines which of the event han-
dler methods of the SBB abstract class is invoked by the SLEE to process the event. Hence, the
event type can be inferred from the event handler method invoked.
• The Activity Context that the event is fired on.
The SLEE passes to the event handler method an object implementing the SBB Activity Context
Interface interface. The SBB entity uses this object to interact with the Activity Context on which
the event was fired and the underlying Activity object of the Activity Context (see Section 7.1.1).
8.3 Event related deployment descriptor elements

The SLEE specification defines two sets of event-related deployment descriptor ele ments:
• Deployment descriptor elements specified by event producers that declare the event types and
event classes that the event producers fire.
• Deployment descriptor elements specified by SBB Developers that declare how SBBs use differ-
ent event types.
8.3.1 Event producer deployment descriptor elements

Every event producer must identify the event types that it fires.
• An SBB declares each event type it fires in an event deployment descriptor element in its sbb
deployment descriptor element.
• A resource adaptor type declares each event type its resource adaptor entities fire in an event de-
ployment descriptor element in its resource-adaptor-type deployment descriptor element.
• Other event producers declare the event types they fire in other deployment descriptors.
An event deployment descriptor element contains an event-type-ref element that references an
event-definition element declared in another deployment descriptor. Each event-definition
element defines an event type.
Each event-definition element contains the following sub-elements:
• An event-type-name element, an event-type-vendor element and an event-type-
version element.
Together, these elements contain the human readable representation of the event type.
• An event-class-name element.
This element provides the Java type for the event parameter of the event handler method that re-
ceives events of the specified event type or the fire event method that fires events of the specified
event type. This means that all events of the same event type must extend a common base class or

Chapter 8
Events
implement a common base interface. In the most generic case, the event class is java.lang.O-
bject.
8.3.2 Event related SBB deployment descriptor elements

The SBB Developer must provide an event element for each event type that the SBB may receive or fire
(see Section 8.1). Each event element contains the following attributes and sub-elements:
• An initial-event attribute.
This attribute indicates if the event type is an initial event (see Section 8.5.1). This attribute is
meaningful only if the SBB is receiving the specified event type.
• An event-direction attribute.
This attribute indicates if the SBB receives or fires the event type identified by the event-
type-ref element of the event element. The value of this attribute can be “Receive”, “Fire”,
or “FireAndReceive”.
• A mask-on-attach attribute.
This attribute indicates whether events of the event type identified by the event-type-ref
element should be masked when an SBB entity attaches to an Activity Context. This attribute is
meaningful only if the event direction is “Receive” or “FireAndReceive”. By default, the event
type is not masked.
• An event-type-ref element.
This element references an event type. It contains the following elements:
o An event-type-name element, an event-type-vendor element, and an
These elements uniquely identify an event type declared in an event-definition
element specified in another deployment descriptor. An event-definition element
declares an event type (see Section 8.3.1)
• An event-name element.
This element provides the SBB scoped name that the SBB uses to refer to the event type identified
by the event-type-ref element (see Section 8.1.10). It is also used to compute the method
names of the event handler method and the fire event method for the event type identified by the
event-type-ref element.
• Zero or more initial-event-select elements.
These elements are only meaningful if initial-event is true. They indicate which conver-
gence name variables should be selected (see Section 8.5.3). It has the following attribute:
o A variable attribute.
The value of this attribute can be one of “ActivityContext”, “AddressProfile”, “Address”,
“EventType”, or “Event”.
• An initial-event-selector-method-name element.
This element is optional and is meaningful only if initial-event is true. It identifies an in itial
event selector method. The SLEE invokes this optional method to d etermine if an event of the
specified event type is an initial event if the SBB is a root SBB of a Service (see Section 8.5.4).
• An event-resource-option element.
This element is optional. It provides additional event handling options that the SLEE forwards to
resource adaptor entities that emit events of the event type identified by the event-type-ref
element. The SLEE does not interpret the content in this element. The event producer of the identi-
fied event type interprets this content.

Chapter 8
Events
For example, the event-resource-option element destined for Java Call Control resource
adaptor entities could specify whether “Notify” or “Block” behavior is desired on a JccConnec-
tion object (a JccConnection object is an Activity object) after a Java Call Control resource
adaptor entity hands an event of the identified event type to the event router. If “Notify” is se-
lected, then the JccConnection object can continue processing and additional events may be
fired on the JccConnection object before this event has been completely processed by the
SBB entities that can receive the event. If “Block” is selected, the JccConnection object can-
not perform further processing and cannot generate additional events. The JccConnection ob-
ject may continue processing after an SBB entity invokes the continueProcessing method
on the JccConnection object.
If different SBBs specify conflicting options, the event producer is responsible for resolving the
conflict. In the above example, if an SBB specifies “Notify” and another specifies “Block”, the
Java Call Control resource adaptor entity may resolve the conflict in favor of “Block”.
8.3.3 Feature interaction analysis

The SBB Developer may use the information present in the event elements to perform feature interaction
analysis during service creation. Service creation tools may also aid feature interaction analysis by present-
ing this information in an SBB Developer friendly manner.
8.4 SBB abstract class and SbbContext interface event methods

The following methods of SBB abstract class of an SBB and the SbbContext interface interact with the
SLEE event router.
• Fire event methods for each event type fired by the SBB.
• Event handler methods for each event type received by the SBB.
• The SbbContext interface maskEvent and getEventMask methods (see Section 8.4.3).
The following methods in the ActivityContextInterface interface, described earlier in Section
7.4, also interact with the SLEE event router.
• The attach method.
This method attaches an SBB entity to an Activity Context. This allows the SBB entity to receive
events fired on the attached Activity Context (see Section 8.5.5).
• The detach method.
This method detaches an SBB entity from an Activity Context. This prevents the SBB entity from
receiving events fired on the just detached Activity Context (see Section 8.5.5).
8.4.1 SBB abstract class fire event methods

For each event type fired by an SBB, the SBB Developer must:
• Provide an event e lement in the SBB’s sbb deployment descriptor element.
The value of the event-direction attribute of the event element must be “Fire” or “Fire -
AndReceive”. The event element must also include an event-name element and an event-
type-ref element. The event-name element provides the SBB scoped name used within the
SBB abstract class to identify the event type and determines the name of the fire event method.
The event-type-ref element references an event-definition ele ment that provides the
event type and the event class.
• Provide an event-definition element if the SBB introduces a new custom event type.
If the custom event type that will be fired by the SBB does not already have an event-
definition deployment descriptor element, the SBB Developer must provide an event-
definition element for the newly introduced custom event type.

Chapter 8
Events
• Declare an abstract fire event method in the SBB abstract class.

The SLEE implements this abstract method when the SBB is installed into the SLEE.
The name of the fire event method is derived from the event name of the event type that will be fired using
the fire event method. The method name of the fire event method is derived by adding a “fire” prefix to the
event name. The fire event method has the following method signature:
public abstract void fire<event name>(<event class> event,
ActivityContextInterface activity,
Address address);
• The fire event method must be declared as public and abstract.

• The fire event method does not have a throws clause.
• The event and activity arguments cannot be null. If either argument is null, the fire
event method throws a java.lang.NullPointerException.
• The address argument provides the optional default address. If there is no default address, then
it should be null.
• As described earlier, an event producer fires an event on an Activity Context and an optional de-
fault address. In the case of an SBB object as an event producer, the SBB object provides an Ac-
tivity Context Interface object to identify the Activity Context, and an Address object to provide
the default address. The address argument must be null if there is no default address. See Sec-
tion 8.5 to learn how the default address influence event routing.
• The SBB object must have an assigned SBB entity when it invokes this method. Otherwise, this
8.4.1.1 Restrictions
The SBB Developer must observe the following restrictions when developing an SBB that fires events.
• An SBB object cannot modify an event object after it passes the event object as an argument to a
fire event method invocation.
• An SBB object cannot modify the event object even after the fire event method returns.
• An SBB object can only invoke its own fire event methods.
• An SBB object can only invoke fire event methods from within an execution thread used to d e-
liver an event to the SBB object.
The execution behavior of the SBB object and the SLEE is undefined if these restrictions are not followed.
8.4.1.2 Example
The following example illustrates an event-definition element, an event element, and a fire event
method of a hypothetical Foo SBB that introduces and fires a new custom event type.
The example event-definition element is as follows:
…
<event-definition>
<description>
An event of this type is fired when a FooActivity starts.
The event class of this event is com.foobar.FooEvent.
This event type identifies a com.foobar.FooEvent with

Chapter 8
Events
getCause() == START_EVENT.
</description>
<event-type-name> com.foobar.FooEvent.StartEvent </event-type-name>
<event-class-name> com.foobar.FooEvent </event-class-name>
</event-definition>
…
The SBB deployment descriptor of the example Foo SBB is as follows:
<sbb>
…
<sbb-classes>
<sbb-abstract-class >
…
com.foobar.FooSbb
…
</sbb-classes>
…
<event event-direction=”Fire”>
<description>
This SBB fires events of the com.foobar.FooEvent.StartEvent
event type and assigns StartEvent as the event name of
this event type.
</description>
<event-name> StartEvent </event-name>
<event-type-ref>
<event-type-name> com.foobar.FooEvent.StartEvent </event-type-name>
</event-type-ref>
</event>
…
</sbb>
The SBB abstract class of the example Foo SBB is as follows:
package com.foobar;
…
public abstract FooSbb implements javax.slee.Sbb … {
…
public abstract void fireStartEvent(com.foobar.FooEvent event,
ActivityContextInterface activity,
Address address);
…
}
8.4.2 SBB abstract class event handler methods

For each event type received by an SBB, the SBB Developer must:
• Provide an event element in the SBB’s sbb deployment descriptor element.
The value of the event-direction attribute of the event element must be “Receive” or
“FireAndReceive”. It must also include an event-name element and an event-type-ref
element. The event-name element provides the SBB scoped name used within the SBB abstract
class to identify the event type and determines the name of the event handler method. The
event-type-ref element references an event-definition element that provides the
event type and the event class. The event-definition element is provided and defined by
the event producer of the event type. The initial-event attribute of the event element may
optionally be set to “true”. The event element may optionally include an event-resource-
option element.

Chapter 8
Events
• Implement an event handler method in the SBB abstract class.

This method contains the application logic that will be invoked to process events of this event
type.
The name of the event handler method is derived from the event name of the event type that will be re-
ceived by the event handler method. The method name of the event handler method is derived by adding an
“on” prefix to the event name. The event handling method has the following method signature:
public void on<event name>(<event class> event,
<SBB Activity Context Interface interface> activity);
• The event handler method must be declared as public and cannot be static, abstract, or
final.
• The event handler method is a mandatory transactional method (see Section 9.6.1). Hence, the
SLEE always invoke this method within a transaction.
• As described earlier, an SBB object as an event consumer receives an event on an Activity Con-
text. This Activity Context is the Activity Context on which the event was fired. In the case of an
event handler method, an SBB Activity Context Interface object (if the SBB defines an SBB Ac-
tivity Context Interface interface) or a generic Activity Context Interface object represents the Ac-
tivity Co ntext on which the event was fired.
• The event handler method may return by throwing a RuntimeException. See Section 6.9 and
Section 6.10.1 on how the SLEE handles this situation.
8.4.2.1 Restrictions
The SBB Developer must observe the following restrictions when developing an SBB that receives events.
• Event handler methods cannot modify event objects passed to it.
• After an event handler method invocation returns, the invoked SBB object cannot continue to hold
a reference to the event object passed to the event handler method, either directly or indirectly
through other objects.
The execution behavior of the SBB object and the SLEE is undefined if these restrictions are not followed.
8.4.2.2 Example
The following example illustrates an event-definition element, an event element, and the event
handler method of a hypothetical Foo SBB that receives an event type whose event type name is
“com.some.event.types.PlayEvent”.
The resource adaptor type’s deployment descriptor contains the following element:
…
<event-definition>
…
<event-type-name> com.some.event.types.PlayEvent </event-type-name>
<event-type-vendor> com.some </event-type-vendor>
<event-type-version> 3.2.1a </event-type-version>
<event-class-name> com.some.events.PlayEvent </event-class-name>
</event-definition>
…
The SBB’s deployment descriptor is as follows:
<sbb>
…
<sbb-classes>
…
com.foobar.FooSbb

Chapter 8
Events
…
<sbb-activity-context-interface>
…
<sbb-activity-context-interface-interface-name>
com.foobar.FooSbbActivityContextInterface
</sbb-activity-context-interface-interface-name>
</sbb-activity-context-interface>
…
</sbb-classes>
…
<event event-direction=”Receive” initial-event=”True”>
…
<event-name> PlayEvent </event-name>
<event-type-ref>
<event-type-name> com.some.event.types.PlayEvent </event-type-name>
<event-type-vendor> com.some </event-type-vendor>
<event-type-version> 3.2.1a </event-type-version>
</event-type-ref>
…
<initial-event-select variable=”AddressProfile”/>
<initial-event-select variable=”ActivityContext”/>
…
</event >
…
</sbb>
In the FooSbb.java:
package com.foobar;
…
public abstract FooSbb implements javax.slee.Sbb {
…
private SbbContext sbbContext;
…
public void setSbbContext(SbbContext context) {
…
sbbContext = context;
…
}
…
public void onPlayEvent(com.some.events.PlayEvent event,
FooSbbActivityContextInterface ac) {
…
if (…) {
…
return;
}
…
if (sbbContext.getRollbackOnly()) {
// do my own cleanup
…
return;
}
return;
}
…
}
8.4.3 SbbContext interface maskEvent and getEventMask methods

An SBB entity can request the SLEE to suspend delivery of events of given event types fired on a given
Activity Context. This is known as event mask ing.
The SbbContext object has a maskEvent method and a getEventMask method.
8.4.3.1 SbbContext interface maskEvent method

The method signature for the maskEvent method is as follows:

Chapter 8
Events
void maskEvent(String[] eventNames, ActivityContextInterface activity)
UnrecognizedEventException,
NotAttachedException,
SLEEException;
• The eventNames argument specifies the event names of the event types that should be masked.
The set of event names specified must identify a subset of the event types that the SBB can re -
ceive, i.e. event names defined in event elements whose event-direction attribute is set to
“Receive” or “FireAndReceive”. A null or empty array argu ment unmasks all previously
masked event types.
• The activity argument identifies the Activity Context whose events should be masked from
the SBB entity assigned to the SBB object that invoked the maskEvent method, i.e. the specified
event mask applies to a specific SBB entity and a specific Activity Context.
• This method throws a java.lang.NullPointerException if the activity argument is
null.
• This method throws a javax.slee.UnrecognizedEventException if one of the event
names specified does not identify an event type that the SBB can receive.
• This method throws a javax.slee.NotAttachedException if the SBB entity is not at-
tached to the specified Activity Context.
• The effects of the maskEvent method are not incremental or cumulative. When the
maskEvent method is invoked twice with two different sets of event names, the second set
overwrites the first set.
• When an SBB entity is initially attached or reattached to an Activity Context, the event types that
are masked are the event types identified by event elements whose mask-on-attach attrib-
ute is set to “True” (see Section 8.3.2).
• An SBB entity can unmask or request the SLEE to resume the delivery of certain event types by
invoking the same maskEvent method. It unmasks a set of event types by invoking the
maskEvent method with a subset of the previously specified set of masked event names. It
would exclude the event names of the event types that should be unmasked from the subset.
• The maskEvent method is a mandatory transactional method (see Section 9.6.1). Hence, the
SBB object must invoke this method within a transaction. It throws a javax.slee.Trans-
• The effects of an invocation of this method are not persistent and visible beyond the current trans-
action until after the transaction commits.
8.4.3.2 SbbContext interface getEventMask method

The method signature for the getEventMask method is as follows:
String[] getEventMask(ActivityContextInterface activity)
NotAttachedException,
SLEEException;

Chapter 8
Events
• This method returns a set of event names. The SBB entity that is assigned to the SBB object of the
SbbContext object uses this method to obtain the set of currently masked event types (refer-
enced by their event names) for the Activity Context identified by the activity arg ument.
• This method throws a java.lang.NullPointerException if the activity argument is
null.
• This method throws a javax.slee.NotAttachedException if the SBB entity is not at-
tached to the specified Activity Context.
• If the SBB entity has not invoked the maskEvent method to set an event mask after the SBB en-
tity is attached or reattached to the Activity Context, then the set of event names returned by the
getEventMask method is the set of event names of event elements whose mask-on-
attach attribute is set to “True”.
• Otherwise, the set of event names returned by the getEventMask method is the same as the set
of event names specified by the most recent maskEvent method for the same SBB entity and
same Activity Context.
• The getEventMask method is a mandatory transactional method (see Section 9.6.1 ). Hence, the
SBB object must invoke this method within a transaction. It throws a javax.slee.Trans-
8.4.3.3 Implementation optimization

A SLEE implementation may filter out masked events immediately before event delivery. As an optimiza-
tion, a SLEE implementation may also modify underlying resource event filters to drop events of masked
event types. It is likely that a SLEE vendor will use both techniques.
8.5 Event routing

The event routing subsystem of the SLEE performs the following functions:
• Instantiate a new root SBB entity of a Service to process events .
• Route an event to the SBB entities that have registered an interest in events of selected event
types.
• Deliver events according to the child relation event priority order.
8.5.1 Initial events

An event that causes the SLEE to instantiate a new root SBB entity of a Service to receive the event is
known as an initial event. The initial event types of the root SBB of a Service identify the event types that
may cause the SLEE to instantiate a new root SBB entity of the Service. They are also known as the initial
event types of the Service.
The set of initial event types of an SBB is a subset of the set of event types that can be received by the
SBB. This is because the SBB must have an event ha ndler method to receive the events of an initial event
type. More precis ely, the initial event types of an SBB are the event types referenced by event elements
within the SBB’s sbb element that have their event-direction attribute set to “Receive” or “FireAn-
dReceive”, and their initial-event attribute set to “True”.
A potential root SBB must have at least one event attribute with the initial-event attribute set to
“True”. However, not all potential root SBBs become a root SBB of an active Service. Since the SLEE only

Chapter 8
Events
instantiates root SBB entities for an active Service, the initial-event attribute is only meaningful
when the SBB is playing the root SBB role of an active Service.
When an event producer fires an event on an Activity Context, the following algorithm is used to determine
whether the event is an initial event for each active Service.
• Determine the set of active Services whose set of initial event types includes the event type of the
event.
• For each Service in this set,
o Compute a convergence name. See Section 8.5.2 below for how this name is computed.
A convergence name is a name used to uniquely identify a root SBB entity belonging to a
Service.
§ If an initial event selector method is provided and it indicates that this event is
not an initial event for this Service (see Section 8.5.4), then the next step is to
start at the beginning of the Service loop and perform initial event processing for
the next Service in the set.
o Look for a root SBB entity of the Service with the convergence name.
o If no such root SBB entity is found, then the event is an initial event for a new root SBB
entity of the Service.
§ Create a new root SBB entity of the Service.
If the creation of the root SBB entity fails, then the following two steps are
skipped. The creation of the root SBB entity may fail because the sbbCreate
method or the sbbPostCreate method returned by throwing an exception
(e.g. a RuntimeException or a CreateException), or because of
SLEE-level or system-level problems. The SLEE should log this occurrence.
§ Assign the convergence name to the new root SBB entity of the Service.
§ Attach the new root SBB entity to the Activity Context on which the event was
fired.
o Otherwise, a root SBB entity is found.
§ If the root SBB entity found is not already attached to the Activity Context on
which the event was fired, then attach the root SBB entity found to the Activity
Context.
When the SBB entity is being attached to the Activity Context, the SLEE event router sets the event mask
of the Activity Context with respect to the SBB entity according to the mask-on-attach attributes of
the event deployment descriptor ele ments of the SBB.
Once the new or existing SBB entity is attached to the Activity Context, the root SBB entity will receive
the event when the SLEE event router delivers the event to the SBB entities attached to the Activity Con-
text (see Section 8.5.8 below).
8.5.2 Computing the convergence name

Logically, the convergence name is a canonical name constructed by concatenating the following variables.
A variable is either selected or not selected (see Section 8.5.3). If a variable is not selected, its value is
null. Otherwise, its value is as specified below.
• Activity Context identifier.
This value of this variable (if selected) is the identifier that uniquely identifies an Activity Context
within the SLEE. This value is SLEE implementation specific and is known only to the SLEE.
There are no SBB visible APIs to obtain or interact with Activity Context identifiers.
Address Profile identifier.
This value of this variable (if selected) is the unique name of an Address Profile , in the Address
Profile Table of the Service, that contains the default address returned by the initial event selector
Chapter 8
Events
method or passed to the event router when the event was fired by the event producer if no initial
event selector method was invoked for the Service . If the default address is null, then the value
of this variable is null.
A default address, or the address returned by an initial event selector method, can only be present
in at most one Address Profile in an Address Profile Table. Hence, a single address maps to at
most one Address Profile identifier and the SLEE constructs at most one convergence name for
the identifier of the at most one Address Profile that the address is present in.
Future releases of the SLEE specification are likely allow a single address to be included in mul-
tiple Address Profiles. In this case, the SLEE will construct a conve rgence name for each Address
Profile identifier that the address maps to.
The default address and the selection of the Address Profile identifier in the convergence name
play an important role in the creation of a convergence name. If the Address Profile identifier is
selected for inclusion in the convergence name and the default address is not null, but a match-
ing Address Profile is not found, no convergence name is created for the SBB for the event and the
event is not an initial event for the SBB. Examples where a matching Address Profile might not be
found are if the default address is not present in the Addresses attribute of any of the profiles in the
Address Profile Table, or if the Address Profile Table for the Service does not exis t in the SLEE.
• Address.
The value of this variable (if selected) is the default address passed to the event router when the
event was fired by the event producer or returned by the initial event selector method. If a default
address is not passed (i.e. the default address is null), then the value of this variable is null.
• Event type.
The value of this variable (if selected) is the event type of the event that was fired.
• Event.
The value of this variable (if selected) is unique for each event fired, e.g. each invocation of an
SBB fire event method or each firing of an event by a resource adaptor (using SLEE vendor spe-
cific fire event methods). It is unique regardless of whether the same pair of event object and Ac-
tivity Context object (in the case of SBB fired event, or Activity object in case of resource adaptor
fired event) are passed to the fire event method. There are two unique events fired in the following
scenarios:
o An SBB invoking the same fire event method twice. From the SLEE’s perspective, the
two fire method invocations fire two unique events even if the Activity Context object
and event object passed to the fire event method are the same.
o An SBB firing an event in its event handler method. The event fired through the fire
event method is a different event even if the same Activity Context object and event ob-
ject passed to the event handler method is passed to the fire event method.
o A resource adaptor entity invoking one or more SLEE provided methods for firing events
multiple times. From the SLEE’s perspective, these invocations fire multiple unique
events even if the Activity object and event object passed are the same.
• Custom name.
If the root SBB of the Service identifies an initial event selector method for the event type, then
the value of this variable is provided by this method. Otherwise, this variable is not selected.
Two convergence names are equal if the values of each of these variables in the two convergence names
are equal.
8.5.3 Selecting convergence name variables

The SLEE provides two mutually exclusive ways to select convergence name variables for each initial
event type.
Chapter 8
Events
• Variable selection by deployment descriptor only.

The variables are selected only by the select deployment descriptor elements in the event de-
ployment descriptor element of each initial event type.
o Each initial-event-select element has a single mandatory variable attribute.
The value of this attribute can be one of the following:
§ “ActivityContext” to select the Activity Context identifier variable.
§ “AddressProfile” to select the Address Profile identifier variable.
§ “Address” to select the address variable.
§ “EventType” to select the event type variable.
§ “Event” to select the event variable.
o The custom name variable is never selected. Only the initial event selector method can
provide a custom name.
• Variable selection by initial event selector method.
The variables are selected at runtime by the initial event selector method.
o The event element must contain an initial-event-selector-method-name
element. The initial-event-selector-method-name element identifies the
initial event selector method for this event type in the SBB abstract class. Multiple initial
event types may share the same initial event selector method.
It is expected that an initial event selector method will be defined for the event types emi t-
ted by each kind of Activity.
o The event element may contain initial-event-select elements. These ele-
ments provide selection hints to the initial event selector method. Ultimately, the initial
event selector method determines which convergence name variables are selected.
o The custom name variable is selected if the custom name value returned by the initial
event selector method is not null.
8.5.4 Initial event selector method

The method signature of the initial event selector method is as follows:
public InitialEventSelector
<initial event selector method name>(InitialEventSelector ies);
• The initial event selector event handler method must be declared as public and cannot be
static , abstract, or final.
• The method name must not begin with “sbb” or “ejb”, and must be a valid Java identifier.
• This method is a non-transactional method.
• It is only invoked on SBB objects in the Pooled state.
The public interface of the InitialEventSelector interface is as follows:
package javax.slee;
public interface InitialEventSelector {

/* attributes for selecting convergence name variables */
public boolean isActivityContextSelected();
public void setActivityContextSelected(boolean select);
public boolean isAddressProfileSelected();
public void setAddressProfileSelected(boolean select);
public boolean isAddressSelected();
public void setAddressSelected(boolean select);
public boolean isEventTypeSelected();
public void setEventTypeSelected(boolean select);

Chapter 8
Events
public boolean isEventSelected();
public void setEventSelected(boolean select);
/* the event name, event object, Activity object, default address, and
custom name */
public String getEventName();
public Object getEvent();
public Object getActivity();
public Address getAddress();
public void setAddress(Address address);
public String getCustomName();
public void setCustomName(String customName);
/* control attribute */
public boolean isPossibleInitialEvent();
public void setPossibleInitialEvent(boolean b);
}
Before the SLEE invokes the initial event selector method, it initialises the InitialEventSelector
object argument to the initial event selector method as follows:
• The <variable>Selected attributes are initialized to true if the event element contains a
select element that selects the convergence variable.
• The eventName and event attributes are initialized according to the event fired by the event
producer. The eventName attribute is initialized with the SBB defined event name correspond-
ing to the event type of the event. The event attribute is initialized with the event object pro-
vided by the event producer or an event object logically equivalent to the event object provided by
the event producer.
The InitialEventSelector object may be instantiated in a different JVM than the event
producer. The event object may be a remote copy of the original event object provided by the event
producer.
• The activity attribute is initialized to the underlying Activity object of the Activity Context
that was provided by the event producer or a logically equivalent Activity object.
• The address attribute is initialized to the default address provided by the event producer. If the
event producer did not provide a default address, this attribute is set to null.
• The customName attribute is set to null.
• The possibleInitialEvent attribute is set to true.
The implementation of the initial event selector method must observe the following rules:
• The method may use the set accessor methods of the InitialEventSelector object to mo d-
ify the InitialEventSelector object.
• It must not mo dify the event object or the Activity object returned by the getEvent method and
getActivity method. If it modifies these objects, then the execution behavior is unspecified.
• It must return the InitialEventSelector object passed in as its argument.
When the initial event selector method returns, the SLEE computes the convergence name as described in
Section 8.5.2 according to the information in the InitialEventSelector object.
• If the possibleInitialEvent attribute is set to false, then the event is not an initial event
for this Service and no further convergence name and initial event processing is performed for this
Service, i.e. the SLEE will not create any new root SBB entity for this Service to process this
event. If this attribute is set to true, then this event is an initial event if the computed conver-
gence name is unique to the Service.
• The selected convergence name variables are determined by the <variable>Selected attrib-
utes of the InitialEventSelector object.

Chapter 8
Events
• The address attribute of the InitialEventSelector object provides the default address.
The value of this attribute may be null if there is no default address. The value of this attribute
determines the value of the address variable in the convergence name if the address variable is se-
lected and is also used to look up Address Profiles in the Address Profile Table of the Service if
the Address Profile variable is selected.
o If the address attribute is null when the initial event selector method returns, then the
address convergence name variable is not selected, i.e. same as setting AddressSe-
lected attribute to false.
o If the AddressProfile variable is set to true and the address is not null but does
not locate any Address Profile in the Address Profile Table of the Service, then no con-
vergence name is created, i.e. same as setting PossibleInitialEvent to false.
• If the value of customName attribute of the InitialEventSelector object is null, then
the custom name variable is not selected.
8.5.5 SBB entities

After the SLEE event router performs the above procedure to instantiate new root SBB entities and to at-
tach root SBB entities to the Activity Context, the SLEE event router begins to d eliver the event to the SBB
entities that may receive the event.
An SBB entity may receive the event if:
• The SBB entity is attached to the Activity Context on which the event was fired.
• The SBB entity has an event handler method for the event type of the event.
• The SBB entity has not masked the event type of the event on the Activity Context.
8.5.6 Concurrency control

The SLEE event router provides the following concurrency control semantics:
• The SLEE event router guarantees that there will be no concurrent execution within a single SBB
object. The SLEE will invoke all the methods of an SBB object serially. These methods include
the event handler methods, the local interface methods, and the life cycle callback methods
• The SLEE event router guarantees that two or more SBB entities will not concurrently receive
events on any single Activity Context. This allows the SBB Developer to develop event handler
methods without having to consider the implications of multiple execution threads that may inter-
act with the same Activity Context and the same underlying Activity object.
• Since an event is always fired on an Activity Context, the SLEE event router will always deliver
the event serially to SBB entities that may receive the event. The order in which these SBB enti-
ties receive the event depends on their event delivery priorities (see Section 8.5.7).
8.5.7 Event delivery priority

The event delivery priority of an SBB entity is determined in the following way:
• The default-priority element of the service deployment descriptor element of a Service
specifies the event delivery priority of the root SBB entities instantiated by the SLEE for the Ser-
vice.
• The default-priority element in the get-child-relation-method element of the
sbb deployment descriptor element of a parent SBB specifies the initial event delivery priority of
the child SBB entities created on this child relation. A parent SBB entity can modify the event de-
livery priority of a child SBB entity at runtime by invoking the setSbbPriority method on an
SBB local object that represents the child SBB entity.

Chapter 8
Events
The event delivery priority of an SBB entity is an integer in the range of -128 through 127, inclusive. -128
is the lowest priority and 127 is the highest priority. The following guidelines for assigning event delivery
priorities should be followed by the SBB Developer and/or Service Deployer to convey an SBB’s sensitiv-
ity to execution order and priority relative to its siblings.
• 100 to 127 for highest event delivery priority.
Child SBB entities of the same parent SBB entity with the highest event delivery priority should
receive the event first.
• 31 to 99 for high event delivery priority.
Child SBB entities of the same parent SBB entity with the high event delivery priority should re-
ceive events earlier than child SBB entities of the same parent SBB entity with standard event de-
livery priority.
• -30 to 30 for standard event delivery priority.
Child SBB entities of the same parent SBB entity with the standard event delivery priority should
receive events earlier than child SBB entities of the same parent SBB entity with low event deliv-
ery priority.
• -99 to –31 for low event delivery priority.
Child SBB entities of the same parent SBB entity with the low event delivery priority should re-
ceive the event later than child SBB entities of the same parent SBB entity with standard event de-
livery priority.
• -128 to -100 for lowest priority.
Child SBB entities of the same parent SBB entity with the lowest event delivery priority should
receive the event last.
8.5.8 Event delivery semantics

The SLEE delivers an event fired on Activity Context in the following way:
• The SLEE delivers the event to a parent SBB entity before it delivers the event to the child SBB
entities of the parent SBB entity.
• Among sibling SBB entities with the same parent, the SLEE delivers the event to a sibling SBB
entity with a higher priority before it delivers the event to a sibling SBB entity with a lower prior-
ity.
• If the sibling SBB entities have child SBB entities, the SLEE delivers the event to the child SBB
entities of the higher priority sibling SBB entity after it delivers the event to the higher priority
sibling SBB entity and before it delivers the event to the lower priority sibling SBB entity. Hence,
the event delivery order is higher priority sibling, children of higher priority sibling, lower priority
sibling, then children of lower priority sibling.
• The order in which an event is delivered to sibling SBB entities with the same event delivery pri-
ority is not specified, i.e. the SLEE implementation determines the order.
• When the SLEE delivers an event to an SBB entity, it checks the event mask associated with the
SBB entity and the Activity Context. If the event is masked, the SLEE does not invoke the event
handler method for the event type of the event. Even though the SBB entity did not receive the
event, the SLEE considers the event delivered to the SBB entity.
• After the SLEE delivers the event to an SBB entity, it determines if one or more SBB entities that
were not attached to the Activity Context prior to delivering the event to the SBB entity have be-
come attached to the Activity Context. If so, the SLEE must deliver the same event to these newly
attached SBB entities.
• The SLEE delivers the event to an SBB entity that stays attached once. The SLEE may deliver the
event to the same SBB entity more than once if it has been detached and then re -attached. For e x-
ample:
o An SBB entity that detaches before it receives the event will not receive the event.
Chapter 8
Events
o An SBB entity that received the event in the past but became detached and then re-
attached will receive the event again if it remains attached and the event is not masked.
8.6 Automatic event subscription

The SLEE must implement automatic event subscription. Automatic event subscription performs the fol-
lowing functions:
• Initial event subscription on behalf of active Services (see Section 8.6.1).
• Received event subscription on behalf of SBB entities (see Section 8.6.2).
The SLEE is expected to collaborate with its resource adaptor entities to automatically install event triggers
and filters into the underlying resources to subscribe and unsubscribe events. These event filters allow the
resource adaptor entities and underlying resources to install the appropriate event triggers and filters close
to the event source and thus avoid transporting a large number of unwanted events to the SLEE.
The current SLEE specification does not define how SLEE vendors should implement automatic event sub-
scription and the API used between the SLEE and resource adaptor entities to perform automatic event sub-
scription. A future specification is expected to define how the SLEE and its resource adaptor entities inter-
act to perform automatic event subscription.
8.6.1 Initial event subscription

The SLEE provides a standard mechanism to help a Service set event filters to subscribe for the initial
events of the potential root SBB entities of the Service (i.e. the initial events of the Service).
The root SBB of a Service specifies the initial event types of the Service. The Address Profile Table of the
Service specifies the subscribed address set of the Service. The Service’s subscribed address set is the set of
addresses in the addresses attribute of all Address Profiles in the Address Profile Table of the Service.
The initial event set of a Service is the cross product of the initial event types of the Service and the Ser-
vice’s subscribed address set. The SLEE’s initial event set is the union of the initial event sets of all active
Services, i.e. Services in the Active state, running in the SLEE.
The SLEE actively modifies the affected event triggers and filters when the SLEE’s initial event set
changes as a result of administrative actions. These administrative actions include:
• Starting and stopping a Service.
The SLEE will only instantiate root SBB entities for active Services. When a Service becomes ac-
tive, the SLEE may have to expand the SLEE’s initial event set to include the initial event set of
the newly active Service. When a Service is deactivated, the SLEE has to contract the SLEE’s ini-
tial event set to exclude the initial event set of the deactivated Service.
• Adding an Address Profile to the Address Profile Table of an active Service, removing an Address
Profile from the Address Profile Table of an active Service, and modifying the addresses in an
Address Profile in the Address Profile Table of an active Service.
These actions indirectly change the SLEE’s initial event set by changing the subscribed address set
of an active Service.
8.6.2 Received event subscription

In addition to the SLEE’s initial event set, the SLEE must also ensure that SBB entities running in the
SLEE receive events of their received event types (which also includes the initial event types). The re-
ceived event set of the SLEE is the set of events that all SBB entities running in the SLEE should receive.
The received event set of the SLEE changes when an operation that modifies the set of events that an SBB
entity can receive is invoked. These operations include:
• Attaching an SBB entity to an Activity Context.
This occurs implicitly when the SLEE instantiates a new SBB entity to handle an initial event of
the SBB (see Section 8.5) or explicitly when the attach method is invoked (see Section 7.4.1).
When this occurs, the SLEE may have to expand the SLEE’s received event set to include events

Chapter 8
Events
of the received event types of the SBB entity. An optimized SLEE implementation may expand
the SLEE’s event set to include only the events of the received event types of the SBB entity that
could be fired by the underlying Activity object of the Activity Context.
• Detaching an SBB entity from an Activity Context.
This occurs implicitly after the SLEE delivers an Activity End Event to an SBB entity (see Section
7.3.3), when the SBB entity is removed (see Section 2.2.6), or explicitly when the detach
method is invoked (see Section 7.4.3). When this occurs, the SLEE may have to contract the
SLEE’s received event set to exclude events of the received event types of the SBB entity.
• Modifying an SBB entity’s event mask on an Activity Context.
This occurs implicitly when an SBB entity invokes the maskEvent method with a different set
of masked event types. When this occurs, the SLEE may have to contract the SLEE’s received
event set if more events types are masked, or the SLEE may have to expand the SLEE’s received
event set if fewer event types are masked.
The SLEE actively modifies affected event filters when the SLEE’s received event set changes.
8.7 Service Started Event and ServiceActivity objects

The Administrator uses the SLEE’s management interface to activate and deactivate Services. Each Service
has an associated Activity. The specific Java type for this Activity is ServiceActivity.
The SLEE fires a Service Started Event on a ServiceActivity object after the Service is started. A
Service is started after one of the following occurs:
• The SLEE is in the Running state and a ServiceManagementMBean object is invoked to acti-
vate the Service, or
• The SLEE becomes active when the SLEE transitions from the Starting to the Running state and
the SLEE starts the Service because the persistent state of the Service says it should be active.
SBBs register interest in Service Started Events like any other event using an event element in their de-
ployment descriptor. An SBB can only receive a Service Started Event fired by the SLEE as an initial event
since this event is fired only once on a ServiceActivity object, at the time the corresponding Service
Activity begins.
Service Started Events enable an SBB to be notified when a Service becomes active. For example, the root
SBB of a Service may listen to Service Started Events by specifying the event type of the Service Started
Event as an initial event type of the SBB. The root SBB of a Wake-up Service may re instate timers from
persistent data stored in Profile Tables. Daemon-like Service entities may also use the Service Started
Event and Service Activity to keep them alive instead of creating and attaching to NullActivity ob-
jects.
8.7.1 Service Activity objects

The SLEE fires a Service Started Event on a ServiceActivity object when the corresponding Service
is started.
• The SLEE is the creator and owner of all ServiceActivity objects. A ServiceActivity
object is created for a Service prior to firing a Service Started Event.
• At any point in time, a Service has at most one ServiceActivity object. If a ServiceAc-
tivity object does not exist when required, it is created by the SLEE.
• The SLEE makes a ServiceActivityFactory object accessible through the environment
component of SBB objects. The ServiceActivityFactory object provides the Ser-
viceActivity object of the Service of the invoking SBB object. The SLEE creates this object
if does not already exist.
The ServiceActivity interface is as follows:

Chapter 8
Events
package javax.slee.serviceactivity;
public interface ServiceActivity {

}
8.7.2 Ending a ServiceActivity object

A ServiceActivity object ends only when the corresponding Service is being stopped by one of the
following occurances:
• A ServiceManagementMBean object is invoked to deactivate the Service.
• The SLEE transitions from the Running state to the Stopping state (implicitly stopping all Ser-
vices).
Daemon-like Service entities with SBB entities that attach only to a ServiceActivity object can use
the natural end of this Activity to help manage their own lifecycle. Since SBB entities are detached from an
Activity when the Activity ends, Service entities with SBB entities that are only attached to a Ser-
viceActivity object will be detached when the Activity ends, causing their attachment count to decre-
ment to zero thus allowing the SLEE to reclaim those Service entities. Optionally, the SBB entities may
define an event handler for the Activity End Event delivered on the ServiceActivity object before it
ends in order to perform any necessary clean-up before the Service is stopped.
8.7.3 Service Started Events

The event-definition element for Service Started Events is as follows:
<event-definition>
…
<event-type-name>
javax.slee.serviceactivity.ServiceStartedEvent
</event-type-name>
<event-class-name>
javax.slee.serviceactivity.ServiceStartedEvent
</event-class-name>
</event-definition>
The ServiceStartedEvent interface is as follows:

public interface ServiceStartedEvent {

}
8.7.4 Service ActivityFactory interface

The SLEE specification defines the ServiceActivityFactory as a Java interface that contains a
single getActivity method. The ServiceActivityFactory object is bound to a SLEE specifica-
tion defined location in the environ ment of every SBB component (see Section 7.10.6).
public interface ServiceActivityFactory {

public ServiceActivity getActivity()
throws TransactionRequiredLocalException, FactoryException;
}
• As this method takes no arguments, it is the responsibility of the SLEE to provide an appropriate
implementation for the SBBs in each Service. The implementation must return a ServiceAc-
tivity object for the Service the invoking SBB entity exists in.
Chapter 8
Events
• This method throws a javax.slee.FactoryException if the method cannot obtain a

ServiceActivity object for the Service because of system-level or SLEE-level problems.
This exception is derived from javax.slee.SLEEException.
8.7.5 Service ActivityContextInterfaceFactor y interface

An SBB can obtain a generic Activity Context Interface object of a Service using a ServiceActivity-
ContextInterfaceFactory object. The ServiceActivityContextInterfaceFactory
object is bound to a SLEE specification defined location in the comp onent environment of every SBB (see
Section 13.8).
public interface ServiceActivityContextInterfaceFactory {

getActivityContextInterface(ServiceActivity serviceActivity)
FactoryException;
}
tional semantics, and the common exceptions thrown by a getActivityContext-
Interface method.
8.7.6 JNDI names of ServiceActivity related objects

The following table lists the names of the SLEE specification defined names for ServiceActivity
related objects under java:comp/env.
Objects Names
ServiceActivityFactory object slee/serviceactivity/factory
ServiceActivityContextInterface- slee/serviceactivity/activitycontextinterfacefactory
Factory object

Chapter 9
Transactions
Chapter 9 Transactions
The previous chapters described the desired behavior of the SLEE and the desired behavior of the comp o-
nents hosted by the SLEE during normal failure -free execution. However, a SLEE running in a real world
environment will encounter failures, such as Java Virtual Machine failures, process failures, host failures,
and resource failures. This chapter defines how the SLEE applies well -established transaction concepts to
address unexpected failures during execution.
All SLEEs must implement the transactional semantics defined in this specification.
Although a SLEE vendor may implement the specified transactional semantics using transactions as de-
fined in the Java Transaction Architecture (JTA), not all SLEE vendors are required to use JTA as the un-
derlying implementation technology. The SLEE specification does not mandate JTA.
9.1 Benefits
Transactions are a proven technique for simplifying application development. The SLEE’s transactional
semantics free the application developer from dealing with many of the issues of failure-recovery and con-
current execution. It allows the developer to design an application as if it were run in an environment that
executes units of work serially with a defined failure model.
9.2 Atomicity
When a transaction executes, it may read and modify execution state directly and may invoke methods that
directly or indirectly read and modify the execution state of the SLEE. The execution state is further parti-
tioned into transactional execution state and non-transactional execution state. Transactional execution
state is state that is associated with a particular transaction and is part of any commit or rollback of the
transaction. Non-transactional execution state is state that is not directly associated with a particular trans-
action. An example of transactional execution state is SBB CMP attributes. An example of non -
transactional execution state is a variable on a thread’s stack.
Atomicity guarantees that when a transaction completes, all changes to the transactional execution state are
applied (committed) or the transactional execution state is restored to its previous value (the transaction is
rolled back). This is often referred to as “all or none” semantics.
The mechanism by which a compliant SLEE implementation provides atomicity guarantees is not defined
by this specification.
9.3 Isolation
All transactions are isolated from each other at the serializable isolation level. This allows multiple units of
work to be executed in parallel provided the end state is guaranteed to be reachable from at least one serial
execution order. This also means changes to the transactional execution state of one transaction are not
vis ible to other concurrently executing transactions.
There are cases where it may be impossible to maintain an isolation guarantee. These cases are covered by
Section 9.11.
The mechanism by which a compliant SLEE implementation provides the isolation guarantee is not defined
by this specification. Examples include the use of an underlying relational database that provides support
for the required isolation, or a local lock manager to serialize access to transactional execution state. These
examples are illustrative rather than prescriptive.
9.4 No demarcation API

The SLEE specification does not define an API that an SBB can use to explicitly define or demarcate trans-
actions. SBB objects can request that transactions be rolled back through the use of the setRollback-
Only method.

Chapter 9
Transactions
9.5 Transaction state machine

The SLEE starts a transaction prior to a SLEE originated invocation sequence (see Section 9.8 for a more
complete description of a SLEE originated invocation sequence). On successful completion of the SLEE
originated invocation sequence the SLEE attempts to commit the transaction.
Each transaction in the SLEE has an implicit state machine. This state machine determines how each trans-
action should behave upon failures, successful or unsuccessful completion of a SLEE originated invocation
sequence.
A transaction may be in one of the following states:
• Active state
• Committing state
• Committed state
• Marked for Rollback state
• Rolling Back state
• Rolled Back state
The SLEE handles all transitions between the various states of the transaction finite state machine. An SBB
object may directly cause a transition between the Active and Marked for Rollback states by invoking the
setRollbackOnly method.
Mark for
Active rollback only Marked for
Rollback
Rollback
Commit Rollback
Committing Rolling Back
Commit with no heuristics Roll back with no heuristics

Commit failure
Commit with Roll back with
likely heuristics likely heuristics
Committed Rolled Back
Figure 10 Transaction state transition diagram
9.5.1 Active state

A transaction enters this state on initialization. A transaction is typically created and initialized prior to the
SLEE originated invocation sequence. When in the Active state, the transaction context is propagated to
any invoked transactional methods (see Section 9.6 for a list of transactional methods).
9.5.2 Committing state

On successful completion of a SLEE originated invocation sequence the transaction transitions from the
Active state to the Committing state. In this state, the transaction is in the process of being committed. If

Chapter 9
Transactions
the commit succeeds the transaction either transitions to the end state or, if heuristics are present, transi-
tions to the Co mmitted state. Otherwise, it enters the Rolled Back state.
9.5.3 Committed state

A transaction enters this state from the Committing state when a heuristic has likely been applied as part of
the commit. If a heuristic has not been applied the transaction would cease to exist. The SLEE specification
does not define the semantics of transaction heuristics in the Committed state. For more information on
possible transaction heuristics refer to JTA.
9.5.4 Marked for Rollback state

The Marked for Rollback state is an extension of the transaction life cycle provided by the SLEE. When a
transaction is in this state the SLEE guarantees that any changes made to the transactional execution state
will be rolled back. A transaction may enter this state from the following state:
• From the Active state:
A transaction enters this state from the Active state when
o The SBB invocation returns abnormally, i.e. it throws a RuntimeException. In this
case, the SLEE marks the transaction for rollback. For further discussion see Section
9.12.
o The SBB invocation directly or indirectly invokes the setRollbackOnly method.
o A transactional method of a SLEE Facility, resource, or EJB marks the transaction for
rollback.
9.5.5 Rolling Back state

A transaction in this state is in the process of rolling back. It may enter this state from the following states:
• From the Marked for Rollback state.
• From the Active state. The SLEE may rollback a transaction due to internal failures. In these
cases, the SLEE originated invocation sequence may have successfully completed execution, e.g.
the methods within the SLEE originated invocation sequence returned without throwing a Run-
timeException.
9.5.6 Rolled Back state

The transaction has been aborted, i.e. the transaction execution state has been restored to its original value.
It may enter this state from the following states:
• From Rolling Back state.
The transaction enters this state from the Rolling Back state when the transaction has rolled back
but the transaction processing indicates that a heuristic has likely been applied as part of the roll-
back. If a heuristic has not been applied the transaction would cease to exist. The SLEE specifica-
tion does not define the semantics of transaction heuristics in the Rolled Back state. For more in-
formation on possible transaction heuristics refer to JTA.
• From the Committing state.
The transaction enters this state from the Committing state when the SLEE is unable to success-
fully commit the transaction. Any updates to the transactional execution state are rolled back on
the transition between the Committing and Rolled Back states. SBB exception handling for this
case is described in Section 6.7. The transaction may fail to commit for various reasons for exa m-
ple underlying resource failures, concurrency control failures, locking or deadlock failures.

Chapter 9
Transactions
9.6 Transactional methods

A transactional method is a method that may directly or indirectly read or modify transactional execution
state. Transactional methods defined by the SLEE specification are further divided into mandatory transac-
tional methods and required transactional methods.
• Mandatory transactional methods are methods that must be invoked from within a transaction. If
they are not invoked from within a transaction the SLEE must throw a javax.slee.Trans-
actionRequiredLocalException.
• Required transactional methods are methods that may or may not be invoked from within a trans-
action. If they are not invoked from within a transaction, a new transaction is created for the dura-
tion of the method invocation.
Both mandatory and required transactional methods execute in the same transaction context as the calling
method.
When a method of a transactional resource or EJB is invoked, this method may or may not be invoked with
a transactional context corresponding to the transaction of the SLEE originated invocation sequence.
Whether this context is propagated depends on the SLEE implementation and the EJB container implemen-
tation. For further discussion, see Section 9.9.
9.6.1 Mandatory transactional methods

These methods may only be invoked from within a transaction in the Active or Marked for Rollback state
otherwise the SLEE must throw a javax.slee.TransactionRequiredLocalException.
• SBB abstract class sbbCreate, sbbPostCreate, sbbRemove, sbbLoad, and sbbStore
life cycle methods.
These methods are also known as the mandatory transactional life cycle methods.
• SBB abstract class event handler and sbbRolledBack methods.
The SLEE cannot invoke any other event handler, or sbbRolledBack method with the same
transaction.
• SBB abstract class CMP field get and set accessor methods.
SBB CMP fields are part of the transactional execution state.
• SBB abstract class fire event methods.
The fire event method of an SBB may be invoked to fire an event that will be processed asynchro-
nously. When an SBB invokes a fire event method the SLEE stores the event internally as part of
its internal transaction processing. The event will be delivered to other SBB entities at some later
time if the transaction successfully commits. If the transaction does not commit successfully the
SLEE discards the event. Each event handler method invoked to process an event fired asynchro-
nously executes within a separate transaction. As other SBB entities will receive the fired event af-
ter the originating transaction has committed, transactional state changes made by the originating
transaction are visible to subsequent event handler method invocations, e.g. state held within an
Activity Context.
• SBB local interface methods.
The methods of an SBB local interface execute in the calling methods transaction context. For e x-
ample if an SBB entity invokes a method on an SBB local interface and the called SBB entity in-
vokes its setRollbackOnly method, then after the invocation returns the callers getRoll-
backOnly returns true.
• Logical cascading removal methods implemented by the SLEE for each SBB (see Section 9.8.1
for more details).
• ChildRelation methods.
The methods of a ChildRelation object execute in the caller’s transaction context. Any trans-

Chapter 9
Transactions
actional state changes caused by child SBB entity creation and removal are viewed as having
taken effect within the calling transaction and only take effect if the calling transaction commits.
• SbbContext interface setRollbackOnly and getRollbackOnly methods.
• ActivityContextInterface interface attach and detach methods.
The effects of these methods are considered transactional, and the state changes caused by these
methods are part of the transaction they are invoked within.
• SbbContext interface maskEvent and getEventMask methods.
The effects of these methods are considered transactional, and take effect as part of the successful
commit of the transaction they are invoked within. Regardless of whether the underlying resource
adaptor entity that fires the specified event types is transactional, the SLEE and the resource adap-
tor entity must collaborate to maintain the atomicity guarantee of the transactional programming
model.
• SbbContext interface getActivities and getSbbLocalObject methods.
• Generic ActivityContextInterface interface methods.
• SBB Activity Context Interface interface attribute get and set accessor methods.
Activity Context attributes are part of the transactional execution state.
• NullActivity interface methods.
When a NullActivity object’s endActivity method is invoked to end the NullActiv-
ity object, this method invocation executes within the current transaction. It only takes effect
when the transaction that the endActivity method is invoked from commits successfully. See
Section 7.10 for details on ending NullActivity objects.
• NullActivityFactory interface methods.
• ServiceActivityFactory interface methods.
• All Activity Context Interface Factory interface methods.
• ActivityContextNamingFacility interface methods.
Bindings/unbindings made via the ActivityContextNamingFacility are transactional,
and take effect as part of the successful commit of the transaction they execute within.
• Transactional methods of transactional resources (see Section 9.9).
9.6.2 Required transactional methods

A required transaction method is a transactional method that may or may not be invoked from within a
transaction in the Active or Marked for Rollback states.
If a required transactional method is invoked from within a transaction, the calling method’s transaction
context is propagated to the called method.
If a required transactional method is invoked fro m a method that is executing outside of a transaction con-
text, a new transaction is started and associated with the method during its invocation. The SLEE attempts
to commit this transaction when the method returns. Once the transaction has committed or rolled back the
calling method resumes execution.
Required transactional methods include:
• All TimerFacility interface methods, except the getResolution method and the get-
DefaultTimeout method.
The setting and cancelling of timers is transactional, the state changes associated with these opera-
tions are part of the transaction the methods execute within.
• All ProfileFacility interface methods.

Chapter 9
Transactions
If a required transactional method is called from a method that does not have an associated transaction and
the newly created transaction fails to commit, the calling method receives a javax.slee.Tran-
sactionRolledbackLocalException.
9.7 Non-transactional methods

A non-transactional method is a method that must not directly or indirectly read or mo dify transactional
execution state. Non-transactional methods include:
• SBB abstract class setSbbContext, unsetSbbContext, sbbActivate and sbbPas-
sivate life cycle methods.
• SbbContext interface getService and getSbb methods.
• All get SBB Usage Parameter methods (see Section 0).
• All methods of non-transactional Facilities.
• All methods of non-transactional resources (see Section 9.11).
• Non-transactional methods of transactional resources.
A non-transactional method is always invoked in an unspecified transaction context.
9.7.1 Unspecified transaction context

The term “an unspecified transaction context” is used in the SLEE specification to refer to the cases in
which the SLEE specification does not fully define the transaction semantics of a method invocation. The
SLEE specification does not prescribe how a SLEE implementation should manage the execution of a
method with an unspecified transaction context, i.e. the transactional semantics are left to the SLEE imple-
mentation.
When the transactional semantics of an unspecified transaction context is unknown, a method that runs
with an unspecified transaction context must be written conservatively and not rely on any particular trans-
action semantics.
A failure that occurs in the middle of the execution of a method that runs with an unspecified transaction
context may leave any resource, transactional and non-transactional state accessed from the method in an
unpredictable state. The SLEE specification does not define how the application should recover state after
such a failure.
9.8 SLEE and non-SLEE originated method invocations

The SLEE may directly or indirectly invoke transactional methods:
• Direct method invocation, also known as SLEE originated method invocation:
The SLEE directly invokes a transactional method if there is no other SBB Developer imple -
mented method invocation, such as an SBB abstract class method, and no other logical cascading
removal method invocation (see below) in the call-chain leading to the current method invocation.
• Indirect method invocation, also known as non-SLEE originat ed method invocation.
The SLEE indirectly invokes a transaction method if there is at least one other SBB Developer
implemented method, such as an SBB abstract class method, or at least one other logical cascading
re moval method invocation in the call-chain leading to the current method invocation.
9.8.1 Special considerations for cascading removal operations

The SLEE implements a logical cascading removal method for each SBB. The SLEE invokes the logical
cascading removal method of an SBB to perform a cascading removal operation on an SBB entity tree or
SBB entity sub-tree whose root SBB entity is an instance of the SBB.
• Logical cascading removal methods are mandatory transactional methods.

Chapter 9
Transactions
• When a logical cascading removal method is invoked, the method invocation may cause additional
transactional methods to be invoked. These additional method invocations are always considered
to be non-SLEE originated method invocations. The transactional methods that may be invoked
include the life cycle methods of the SBB entities in the SBB entity tree or the SBB entity sub-tree
being re moved.
A logical cascading removal method invocation may be a SLEE originated method invocation or a non-
SLEE originated method invocation.
• A SLEE originated logical cascading removal method invocation is initiated by the SLEE to re-
claim an SBB entity tree after the attachment count of the root SBB entity of the SBB entity tree
decreases to zero. When the method invocation completes, an entire SBB entity tree should be re-
moved.
The SLEE specification does not specify whether or not the SLEE invokes the logical cascading
removal method in the same transaction that decreases the attachment count of the root SBB to
zero. Thus, a SLEE may implement eager and/or lazy reclamation o f SBB entity trees. If the cas-
cading re moval operation does not occur in the same transaction (i.e. eager reclamation), the
SLEE must behave as if the SBB entity tree has become non-existent. It must remove any conver-
gence name associated with the root SBB entity of the SBB entity tree, i.e. the same convergence
name may cause the SLEE to instantiate a new root SBB entity. It must also not deliver events to
SBB entities in the “non-existent” SBB entity tree.
• A non-SLEE originated logical cascading removal method invocation is initiated by an SBB to
remove an SBB entity tree by invoking the remove method on an SBB local object, or invoking
one of the remove methods on a ChildRelation object.
In summary, the only SLEE originated method invocation in a cascading removal operation is the SLEE
invoking a logical cascading removal method to remove an SBB entity tree after the attachment count of
the root SBB entity of the SBB entity decreases to zero. Non-SLEE originated logical cascading removal
method invocations and all additional transactional methods invoked within a SLEE or a non-SLEE origi-
nated cascading removal method invocation are considered to be non-SLEE originated method invocations.
9.8.2 SLEE originated invocation

A SLEE originated invocation consists of all the transactional method invocations invoked directly by the
SLEE within the same transaction on either a single SBB object or a single SBB entity. Each SLEE origi-
nated invocation must include at least one SLEE originated mandatory transactional method invocation.
The possible types of SLEE originated invocations are as follow:
• Life Cycle Only.
o The possible SLEE originated method invocations within a SLEE originated invocation
of this type are as follows:
§ at least one mandatory transactional life cycle method invocations, followed by
§ at most one sbbExceptionThrown method invocation.
o Within a SLEE originated invocation, these methods must be invoked on the same SBB
object, also known as the target SBB object of the SLEE originated invocation.
o If the target SBB object enters the Ready state, then the target SBB entity of the SLEE
originated invocation is the SBB entity represented by the SBB o bject.
• Remove Only .
§ a SLEE originated logical cascading removal method invocation.

Chapter 9
Transactions
o The target SBB entity of a Remove Only SLEE originated invocation is the root SBB en-
tity of the SBB entity tree being removed. There is no target SBB object in a Remove
Only SLEE originated invocation.
• Op Only.
§ zero or more mandatory t ransactional life cycle method invocations, followed by
§ an invocation of either an event handler method or a sbbRolledBack
method, fo llowed by
§ zero or more mandatory t ransactional life cycle method invocations, followed by
§ at most one sbbExceptionThrown method invocation.
o Within a SLEE originated invocation, these methods must be invoked on the same SBB
object, also known as the target SBB object of the SLEE originated invocation.
o If the SBB object enters the Ready state, then the target SBB entity of the SLEE origi-
nated invocation is the SBB entity represented by the SBB object.
o The SBB object must enter the Ready state for the SLEE to invoke its event handler
method or its sbbRolledBack method .
• Op And Remove.
§ zero or more mandatory transactional life cycle method invocations, followed by
§ an invocation of either an event handler method or a sbbRolledBack
method, fo llowed by
§ zero or more mandatory transactional life cycle method invocations, followed by
§ at most one sbbExceptionThrown method invocation, followed by
§ a logical cascading removal method invocation.
o Within a SLEE originated invocation, these methods, except the logical cascading re-
moval method invocation, must be invoked on the same SBB object, also known as the
target SBB object of the SLEE originated invocation. The SBB o b ject must be in the
Ready state when its event handler method or its sbbRolledBack method is invoked.
o The target SBB entity of a SLEE originated invocation of this type is the SBB entity rep-
resented by the target SBB object.
The target SBB entity is always known since the target SBB object must be in the Ready
state.
o The SBB entity tree or SBB entity sub-tree to be removed by the logical cascading re-
moval method invocation within a SLEE originated invocation of this type must be the
SBB entity tree or SBB entity sub-tree rooted by the target SBB entity.
If any of the methods (except the sbbExceptionThrown method) invoked on the target SBB object of a
SLEE originated invocation returns by throwing a RuntimeException, then the SLEE invokes the
sbbExceptionThrown method of the target SBB object of the transaction within the same transaction.
There is at most one sbbExceptionThrown method invocation in each of the above SLEE originated
invocation types since the SLEE will move the target SBB object of the SLEE originated invocation to the
Does Not Exist state after invoking the sbbExceptionThrown method once on the SBB object. The
SLEE will not invoke any oth er methods on the SBB object once it enters the Does Not Exist state.
Each of the SLEE originated mandatory transactional method invocations may in turn invoke other meth-
ods.

Chapter 9
Transactions
• If an invoked method is a transactional method (mandatory or required), then the invoked method
run in the same transaction as the SLEE originated mandatory transactional method invocation.
• If an invoked method is a non-transactional method, then the invoked method does not run in the
same transaction as the SLEE originated mandatory transactional method invocation. The invoked
method runs with an unspecified transaction context (see Section 9.7.1).
9.8.3 SLEE originated invocations and transactions

Each transaction initiated by the SLEE must be described by a valid SLEE originated invocation sequence.
A SLEE originated invocation sequence is an ordered sequence of one or more SLEE originated invoca-
tions. The SLEE completes a SLEE originated invocation in the ordered sequence before beginning the
next SLEE originated invocation in the o rdered sequence.
The following rules apply to valid sequences.
• A valid sequence contains at most one Op Only or Op And Remove SLEE originated invocation.
This means that each transaction may contain at most one event handler or sbbRolledBack
method invocation.
• A valid sequence contains at most one Remove Only or Op And Remove SLEE originated invoca-
tion. This means that each transaction may only contain one SLEE originated logical cascading
removal method invocation.
o If the sequence contains a Remove Only or an Op And Remove SLEE originated invoca-
tion, then the Remove Only or an Op And Remove SLEE originated invocation must be
the last SLEE originated invocation in the sequence.
o If the sequence contains one Op Only and one Remove Only SLEE originated invoca-
tions, then the target SBB object invoked by the Op Only SLEE originated invocation
must enter the Ready state or be in the Ready state, and the target SBB entity of the Re-
move Only SLEE originated invocation must be the root SBB entity of the target SBB
entity invoked by the Op Only SLEE originated invocation.
• A valid sequence does not contain SLEE originated method invocations on more than one SBB
object that enters the Ready state from the Pooled state or is already in the Ready state.
A SLEE originated logical cascading removal method invocation does not directly invoke any
methods on an SBB object. The method directly invoked is the logical cascading removal method.
The logical cascading removal method is logically a SLEE implemented method for each SBB. The
SLEE must invoke this method on an SBB entity to initiate a cascading removal of the SBB entity
tree rooted by the SBB entity. Logically, this method implements the cascading removal operation
and is only invoked by SLEE on the root of the SBB entity tree (i.e. not invoked on the descendent
SBB entities in the SBB entity tree). An invocation of this method on the root of the SBB entity tree
is considered a SLEE originated invocation. All sbbRemove callback s, and any local interface
method calls invoked by an sbbRemove callback , are not considered to be directly invoked by
the SLEE and are not SLEE originated invocations.
When a SLEE originated sbbPostCreate method invocation returns without throwing a Run-
timeException, the sequence is considered to have invoked an SBB object that enters the
Ready state from the Pooled state.
9.8.4 Examples of valid SLEE originated invocation sequences

The following list describes several example valid SLEE originated invocation sequences :
• This example sequence does not invoke any SBB entities.
The SLEE directly invokes a single SBB objects in the Pooled state in this sequence. There is Life
Cycle Only SLEE originated invocation in the sequence and the target SBB object invoked re -
mains in the Pooled state.

Chapter 9
Transactions
• This example seque nce invokes a single SBB entity.

The SLEE directly invokes a single SBB object that represents the single SBB entity. There is a
single SLEE originated invocation in the sequence. The types of the SLEE originated invocation
in the sequence can be:
o Life Cycle Only if the SBB object enters the Ready state, or
o Op Only.
• This example sequence invokes a root SBB entity and a logical cascading removal method to re-
move the root SBB entity.
The SLEE directly invokes a single SBB object that represents the root SBB entity. One of these
invocations causes the attachment count of the root SBB entity to decrease to zero. The SLEE d i-
rectly invokes the appropriate logical cascading removal method to remove the SBB entity tree.
There is a one SLEE originated invocation in the sequence and the type of the only SLEE origi-
nated invocation in the sequence is Op and Re move.
• This example sequence invokes a single non-root SBB entity and a logical cascading removal
method to remove the root SBB entity of the non-root SBB entity.
The SLEE directly invokes a single non-root SBB object that represents a non-root SBB entity.
One of these invocations causes the attachment count of the root SBB entity of the same SBB en-
tity tree to d ecrease to zero. The SLEE directly invokes the appropriate logical cascading removal
method to remove the SBB entity tree. There are two SLEE originated invocations in the se-
quence. The types of the first SLEE originated invocation in the sequence can be:
o Life Cycle Only if the SBB object enters the Ready state, or
o Op Only.
The type of the second SLEE originated invocation in the sequence is Remove-Only.
9.8.5 An illustrated example of a transaction

Figure 11 illustrates a example transaction whose SLEE originated invocation sequence consists of a single
Op Only SLEE originated invocation. In this example, the event is an initial event for the SBB. When this
occurs, the SLEE creates an SBB entity and assigns it to an SBB object. The SLEE invokes the sbbCre-
ate and sbbPostCreate life cycle methods, the event handler method for the event, and the sbb-
Store life cycle method with the same transaction. In this example the event processing completes suc-
cessfully, i.e. without throwing a RuntimeException.
: EventRouter : FooSbb t : Transaction
begin( )
sbbCreate( )
sbbPostCreate( )
onFooEvent( )
sbbStore( )
commit( )
Figure 11 Transactional behavior of an SBB invocation that returns normally
9.9 Transactional resources and EJB invocations

There are two types of transactional resource:

Chapter 9
Transactions
• JTA transactional resources.

A JTA transaction resource is a XA resource as defined by JTA.
• Non-JTA transactional resources.
A non-JTA transactional resource supports transactions in a resource specific manner, such as a
JDBC 2.0 driver that does not implement javax.transaction.xa.XAResource.
The SLEE specification does not require a SLEE to support JTA transactional resources.
If the SLEE implementation uses JTA to implement transactions and the resource implements JTA transac-
tions, or if the resource supports transactions in a resource specific manner and the SLEE is integrated with
this resource specific transaction API, when a method on the resource is invoked within a transaction the
SLEE implementation may:
• Invoke the resource with no transaction context.
• Treat each invocation of the resource as a single transaction.
• Invoke the resource under the event handler transaction context.
• Combine multiple invocations to multiple resources under the calling transaction.
The exact characteristics depend on the implementation of both the SLEE and the resource.
A SLEE may integrate with EJB 2.0 containers to support transaction context propagation when methods
on EJB interfaces are invoked within a transaction.
9.10 FIFO ordering of asynchronously fired events

When more than one event is fired on a particular Activity Context within the same transaction, the order of
receipt of the events must be the order of the firing of events.
9.11 Non-transactional resources.

It is highly likely that resources used by SBBs within the SLEE are non-transactional. For example many
call control resources such as soft switches, call agents, class 4 or 5 switches, SIP proxies, … etc. do not
provide transactional semantics.
The SBB Developer must be aware that combining transactional and non-transactional resources in the
same transaction may violate properties of the transactional programming model such as the atomicity
guarantee. For example a transaction may update transactional state and then modify a non-transactional
resource. If the transaction is rolled back, updates to the non-transactional resource re main.
9.12 Transactions exception handling and rolle d back handling

There are two cases for the behavior of the SLEE when a method invocation throws an exception. These
cases are:
• Non-SLEE originated method invocation.
• SLEE originated method invocation.
It can be seen from these two cases that the SLEE is the initiator in one case and SBB application logic is
the initiator in the other. As SBBs are of arbitrary complexity, SBBs are expected to handle exceptional
situations through a callee or caller/callee local interface contract. The SLEE is not of arbitrary complex-
ity, its semantics are defined in this specification. Therefore if the SLEE initiates an invocation, a mecha-
nism must be defined to allow the SLEE to inform the SBB of some unexpected situation (for example a
resource fails after the SBB event handler invocation returns and before the transaction has committed
causing the transaction to rollback, or a deadlock occurs causing the transaction to be rolled back).
Both SLEE originated and non-SLEE originated method invocations may also explicitly cause transactions
to roll back through the use of the setRollbackOnly method regardless of whether the method invoca-
tion returns by throwing an exception or not. Resources may also request that transactions be rolled back.

Chapter 9
Transactions
Errors related to SLEE originated or non-SLEE originated method invocations may occur outside of invo-
cation itself. Resource failures may cause these errors. These errors may also cause transactions to roll
back.
9.12.1 Non-SLEE originated method invocation

If a non-SLEE originated method invocation returns by throwing a checked exception, then the following
occurs:
• The state of the transaction is unaffected
• The checked exception is propagated to the caller.
It is expected that the caller will have the appropriate logic to handle the exception.
If a non-SLEE originated method invocation returns by throwing a RuntimeException, then:
• The transaction is marked for rollback.
• The SBB object that was invoked is discarded, i.e. is moved to the Does Not Exist state.
• A javax.slee.TransactionRolledBackLocalException is propagated to the caller.
The transaction will eventually be rolled back when the highest level SLEE originated invocation re-
turns as described in Section 9.12.2.
The sbbRolledBack method is not invoked for an SBB originated method transaction because the
transa ction is only marked for rollback and will only be rolled back when the highest level SLEE
originated invocation returns. The sbbRolledBack method is only invoked on the SBB entity in-
voked by the highest level SLEE originated invocation.
If the RuntimeException propagates to the highest level (i.e. the SLEE originated method invocation
returns by throwing a RuntimeException) the SLEE originated method invocation exception handling
mechanism is init iated.
9.12.2 SLEE originated method invocation

If all the method invocations belonging to SLEE originated invocation return without throwing an excep-
tion or by throwing only checked exceptions, then the following occurs:
• If the transaction is not marked for rollback, then:
o The transaction is moved to the Committing state, i.e . attempt to commit transaction.
o If the transaction cannot be committed, then:
§ The transaction is rolled back.
§ If the SLEE originated method invocation has a target SBB entity (see Section
9.8.2), the SLEE eventually invokes the sbbRolledBack method in a new
transaction on another SBB object that represents the same SBB entity as de-
scribed in Section 6.10.1.
• If transaction is marked for rollback, then:
o The transaction is rolled back.
o If the SLEE originated method invocation has a target SBB entity (see Section 9.8.2), the
SLEE eventually invokes the sbbRolledBack method in a new transaction on another
SBB object that represents the same SBB entity as described in Section 6.10.1.
The only SLEE originated method invocations that may throw a checked exception are sbbCreate
and sbbPostCreate method invocations. If an sbbCreate or an sbbPostCreate method does
not want the SBB entity to be created when it throws a CreateException (or return without throw-
ing an exception), it can invoke the setRollbackOnly method to mark the transaction for rollback.

Chapter 9
Transactions
If a SLEE originated method invocation returns by throwing a RuntimeException, then the following
occurs:
• The transaction is marked for rollback.
• The sbbExceptionThrown callback method is invoked as defined in Section 6.9.
• The SBB object that was invoked is discarded, i.e. moved to the Does Not Exist state.
• The transaction is eventually rolled back.
• If the SLEE originated method invocation has a target SBB entity (see Section 9.8.2), and the
SLEE was not invoking the sbbRolledBack method on the target SBB entity the SLEE even-
tually invokes the sbbRolledBack method in a new transaction on a nother SBB object that
represents the same SBB entity as described in Section 6.10.1 .
If a transaction that includes a SLEE originated logical cascading removal method invocation does not
commit (because the sbbRemove method of one of SBBs invoked returns by throwing a RuntimeEx-
ception or marks the transaction for roll back, or for some other reasons like optimistic concurrency con-
trol conflicts, deadlocks, or internal SLEE problems), the SLEE is expected to forcefully remove the SBB
entity tree that would have been removed by the SLEE originated logical cascading removal method invo-
cation after the SLEE has invoked the sbbRolledBack callback corresponding to the transaction that did
not commit.
9.12.3 SLEE originated transaction exception and rolled back handling

example
The following example illustrates the behavior of SLEE when a RuntimeException propagates from a
SLEE originated method invocation. The SLEE catches the exception, marks the transaction for rollback,
invokes the sbbExceptionThrown method on the SBB object and rolls back the transaction. It then
starts a new transaction and invokes the sbbRolledBack on another SBB object. The second SBB object
has access to the same persis tent state, i.e. it is assigned to the same SBB entity (see Section 6.2). It then
commits the transaction. Note that the diagram assumes that the first SBB object is already in the ready
state .

Chapter 9
Transactions
: EventRouter a : FooSbb t : Transaction a' : FooSbb : Transaction
begin( )
onBarEvent( )
the event handler method returns by

markForRollback(t) throwing an unchecked exception
sbbExceptionThrown( )
rollback( )
begin( )
sbbActivate( )
sbbLoad( )
sbbRolledBack is called on a new SBB
sbbRolledBack( ) object (a') that has the same CMP state
as SBB object a
sbbStore( )
commit( )
Figure 12 Transactional behavior of an SBB invocation that returns abnormally
9.12.4 Transaction rolled back callback handling

When a transaction rolls back, the SLEE should deliver a transaction rolled back callback for each SLEE
originated invocation in the transaction that has a target SBB entity. The SLEE delivers each of these
transaction rolled back callbacks by invoking the sbbRolledBack method in a new transaction on an-
other SBB object that represents the corresponding target SBB entity.

Chapter 10
Profiles and Profile Specifications
Chapter 10 Profiles and Profile Specifications

A Profile contains provisioned data. The schema of the Profile defines the attributes that may be provi-
sioned in the Profile. A Profile Table contains zero or more Profiles that conform to the same schema. A
Profile Specification defines the interfaces, classes, and deployment descriptor elements needed to define a
Profile schema and the interfaces used to provision and access a Profile that conforms to the Profile
schema. Zero or more Profile Tables can have the same Profile Specification.
10.1 Introduction
When developing an SBB, the SBB Developer may define zero or more Profile Specifications. Each Profile
Specification specifies a kind of provisioned data required by the SBB to perform its function. The Profile
Specification describes the schema of Profile Tables created from the Profile Specification by the Adminis -
trator. More precisely, it defines the set of attributes of every Profile Table created from the Profile Specifi-
cation. Every Profile in these Profile Tables has the same attributes.
The SBB Developer defines a Profile Specification through a set of Java interfaces, classes, and a deploy-
ment descriptor. These interfaces, classes, and deployment descriptor define the three views of a Profile.
The three views are the SBB Developer’s SBB object view (see Section 10.5.1), the SBB Developer’s man-
agement view (see Section 10.5.2), and the Administrator’s view (see Section 10.5.3).
The SBB Developer packages these Java class files and the deployment descriptor into a Profile Specifica-
tion jar file. The Service Deployer packages the Profile Specification into a deployable unit. The Adminis-
trator deploys this deployable unit into the SLEE. Once the Profile Specification is deployed, the Adminis-
trator can create Profile Tables of the Profile Specification. Each Profile Table has a name, known as the
Profile Table name. Once a Profile Table has been created, the Administrator may add Profiles to the Pro-
file Table. Each Profile within a Profile Table must have a unique name within the Profile Table. This
name is known as the Profile name. The Profile Table name and Profile name together uniquely identify a
Profile within the SLEE. This is known as the Profile identifier.
10.1.1 Relationships
Profile Specifications, Profile Tables, and Profiles participate in the following relationships:
• Profile Specifications and Profile Tables: 1-to-many
The Administrator may create multiple Profile Tables from the same Profile Specification. How-
ever, each Profile Table is created to conform to exactly one Profile Specification.
• Profile Tables and Profiles: 1-to-many
Each Profile may belong to only one Profile Table. A Profile Table may contain zero or more Pro-
files.
• Profiles and Profiles: many-to-many
Each Profile may reference another Profile or itself (see Section 10.6.1). The SLEE does not im-
pose any restrictions on the Profile references.
• Address Profile Tables and Services: 1-to-many
Each Service may optionally reference an Address Profile Table. The same Address Profile Table
may be referenced by more than one Service (see Section 10.13.2).
• Resource Info Profile Tables and Services: 1-to-many
Each Service may optionally reference a Resource Info Profile Table. The same Resource Info
Profile Table may be referenced by more than one Service (see Section 10.13.1).
10.1.2 Profile Table names, Profile names, and Profile identifiers

The following names and identifiers are used to identify Profile Tables and Profiles.
• Profile Table name.
The Administrator must assign a globally unique name to each Profile Table, known as the Profile
Chapter 10
Table name. The Java type for Profile Table names is java.lang.String. A Profile Table
name cannot be null or zero-length, and may only contain letter or digit characters as defined by
java.lang.Character.isLetter and java.lang.Character.isDigit. Addi-
tionally, any other character in the Unicode range 0x0020-0x007e may be included in a Profile
Table name, except for the ‘/’ character (Unicode 0x002f).
• Profile name.
Each Profile within a Profile Table must have a unique name within the Profile Table. This name
is known as the Profile name. The Java type for Profile names is java.lang.String. A Pro-
file name cannot be null or zero-length, and may only contain letter or digit characters as de-
fined by java.lang.Character.isLetter and java.lang.Character.isDigit.
Additionally, any other character in the Unicode range 0x0020 -0x007e may be included in a Pro-
file name.
• Profile identifier.
The Profile Table name and Profile name together uniquely identify a Profile within the SLEE.
This is known as the Profile identifier. The Java type that encapsulates Profile identifiers is the
ProfileID class (see Section 10.2).
10.1.3 Profile Table and Profile addresses

The following kinds of addresses also identify Profile Tables and Profiles within Profile Tables.
• Profile Table address.
A Profile Table can also be identified by an Address object. The address plan of this Address
object is SLEE_PROFILE_TABLE and the address string contains the Profile Table’s name.
• Profile address.
A Profile can also be identified by an Address object. The address plan of this Address object
is SLEE_PROFILE and the address string contains the Profile identifier encoded as “pro-
file_table_name/profile_name”.
The address form of identifying Profile Tables and Profiles allows Profile Tables and Profiles to be identi-
fied in the addresses attribute of Address Profile Tables (see Section 10.13.2), and allows Profile Added
Events, Profile Removed Events, and Profile Updated Events to be initial events.
10.1.4 Default Profile of a Profile Table

Each Profile Table has a default Profile t hat is specific to the Profile Table.
• When the Profile Table is created, the persistent state of the default Profile is initialized by the
profileInitialize method (see Section 10.9.3) of the Profile Manageme nt abstract class (if
one is defined).
• In addition, an Administrator can update the default Profile of the Profile Table through the
SLEE’s management interface.
• When an Administrator adds a Profile to the Profile Table, the SLEE copies the persistent state of
the default Profile to the new Profile. The default Profile of a Profile Table provides the initial
values for the attributes of new Profiles of the same Profile Table.
10.2 ProfileID class

The public interface of the ProfileID class is as follows:
package javax.slee.profile;
import java.io.Serializable;
import javax.slee.Address;
public class ProfileID implements Serializable {

Chapter 10
public ProfileID(String profileTableName, String profileName)
throws NullPointerException, IllegalArgumentException { … }
public ProfileID(Address address)
public String getProfileTableName() { … }
public String getProfileName() { … }
public void setProfileID(String profileTableName, String profileName)
public Address toAddress() { … }
public boolean equals(Object obj) { … }
}
• The equals method.
This method indicates whether the specified object (specified by the obj argument) is equal to
this Profile identifier. The specified object is equal to this Profile identifier if the specified object
is a Profile identifier and the names of the Profile Table and Profile in the specified Profile identi-
fier is the same as this Profile identifier.
• The hashCode method.
The implementation of this method should provide a reasonable hash code value for the Profile
identifier.
The above methods may throw the following exceptions:
• java.lang.NullPointerException.
If any of a method’s arguments (profileTableName, profileName, or address ) are
null, the method throws a NullPointerException.
• java.lang.IllegalArgumentException.
If the profileTableName argument contains the “/” character, or the address argument
does not have an address plan of SLEE_PROFILE or the address string is not valid for the
SLEE_PROFILE address plan, the method throws an IllegalArgumentException.
10.3 Profile Table Events and ProfileTableActivity objects

The Administrator uses the SLEE’s management interface to add and remove Profiles from Profile Tables.
Each Profile Table has an associated Activity. The Java object that encapsulates this Activity is a Profi-
leTableActivity object. The SLEE fires the following types of events on a ProfileTableAc-
tivity object.
• Profile Added Event.
After a Profile is added to a Profile Table, the SLEE fires a Profile Added Event on the Profile Ta-
ble’s Activity.
• Profile Updated Event.
After a Profile has been updated, the SLEE fires a Profile Updated Event on the Profile Table’s
Activity.
• Profile Removed Event.
After a Profile is removed from a Profile Table, the SLEE fires and delivers a Profile Removed
Event on the Profile Table’s Activity.
These events are also known as the Profile Table Events.
Collectively, these events enable an SBB entity to be notified of additions, updates, and deletions to Profile
Tables so that it can act on these changes with a valid transaction context. The SLEE invokes the event
handler methods for these Profile Table Events within a transaction and these event handler methods can
act on the Profile Table additions, updates, and deletions with full access to the runtime environment.
SBBs register interest in these events like any other events using event elements in their deployment de-
scriptors and by attaching to the appropriate Activity Contexts.

Chapter 10
10.3.1 ProfileTableActivity objects

The SLEE fires Profile Table Events on ProfileTableActivity objects.
• The SLEE is the creator and owner of all ProfileTableActivity objects.
• At any point in time, a Profile Table has at most one ProfileTableActivity object. If a
ProfileTableActivity object does not exist when required, for example to fire a Profile
Table Event, it is created by the SLEE.
• When a Profile Table is removed from the SLEE by an Administrator using a ProfileProvi-
sioningMBean object, the SLEE ends the corresponding Profile Table Activity and fires an Ac-
tivity End Event on its ProfileTableActivity object. Additionally, the SLEE ends all Pro-
file Table Activities , and fires Activity End Events on the corresponding ProfileTableAc-
tivity objects, when the SLEE transitions from the Running state to the Stopping state. This al-
lows SBB entities attached to Profile Table Activities to clean up in the usual way.
The ProfileTableActivity interface is as follows:
public interface ProfileTableActivity {

public String getProfileTableName();
}
10.3.2 Profile Added Events

The event-definition element for Profile Added Events is as follows:
<event-definition>
…
<event-type-name> javax.slee.profile.ProfileAddedEvent </event-type-name>
<event-class-name> javax.slee.profile.ProfileAddedEvent </event-class-name>
</event-definition>
The ProfileAddedEvent interface is as follows:

public interface ProfileAddedEvent {

public Address getProfileAddress();
public ProfileID getProfile();
public Object getAddedProfile();
}
• The getProfileAddress method returns an Address object identifying the Profile that has
been added. When an event is fired, the event producer may optionally provide to the event router
a default address that is used to route the event (see Section 8.2.1). In the case of a Profile Added
Event, the SLEE is the event producer and the default address provided by the SLEE for the Pro-
file Added Event is the address returned by this method.
• The getProfile method returns the Profile identifier of the Profile added to the Profile Table.
The Profile identifier may or may not identify an existing Profile in the Profile Table. For exa m-
ple, the Profile identifier does not identify an existing Profile in the Profile Table if the Profile has
been deleted after it was added but before the SLEE delivers the event.
• The getAddedProfile method returns a read-only Profile CMP object that provides the con-
tent of the Profile when the Profile was added.
o The Java type of the Profile CMP object is the Profile CMP interface defined by Profile
Specification of the Profile Table identified by the Profile identifier returned by the get-

Chapter 10
Profile method. Therefore, Java typecast can be used to narrow the returned object to
the Profile CMP interface or a base interface of the Profile CMP interface.
o The values in the attributes of this Profile CMP object are the values present in the Profile
when the Profile was added to the Profile Table. These values may be different from the
attribute values in the Profile obtained from the Profile identifier returned by the get-
Profile method (if the Profile identifier identifies a Profile). The values may be differ-
ent if the Profile identified by the Profile identifier has been modified after the Profile
was added.
o The Profile CMP object returned by an invocation of this method is only valid within the
same transaction that the invocation occurred in. (The same event may be re-fired and
processed in a new transaction, if this method is invoked to obtain another Profile CMP
object, this new Profile CMP object will only be valid within the new transaction.)
o This method may return null if the relevant profile specification implementation classes
for the profile are not available in the classloader of an SBB which receives this event.
This may occur, for example, if an SBB entity attaches to the Profile Table Activity of a
profile table for which the SBB of the SBB entity has not declared a profile-spec-
ref entry in its deployment descriptor for the profile specification of the profile table.
10.3.3 Profile Updated Events

The event-definition element for Profile Updated Events is as follows:
<event-definition>
…
<event-type-name> javax.slee.profile.ProfileUpdatedEvent </event-type-name>
<event-class-name> javax.slee.profile.ProfileUpdatedEvent </event-class-name>
</event-definition>
The ProfileUpdatedEvent interface is as follows:

public interface ProfileUpdatedEvent {

public Object getBeforeUpdateProfile();
public Object getAfterUpdateProfile();
}
• The getProfileAddress method returns an Address object that identifies the Profile that
has been updated. When an event is fired, the event producer may optionally provide to the event
router a default address (see Section 8.2.1). In the case of a Profile Updated Event, the default ad-
dress is the address returned by this method.
• The getProfile method returns the Profile identifier of the Profile updated. The Profile identi-
fier may or may not identify an existing Profile in the Profile Table. For example, the Profile iden-
tifier identifies may not identify an existing Profile in the Profile Table if the Profile has been re-
moved after the Profile was updated but before the SLEE delivers the event.
• The getBeforeUpdateProfile method and the getAfterUpdateProfile method re-
turn read-only Profile CMP objects that provide the content of the Profile before and after the Pro-
file was updated, respectively.
o The Java type of the Profile CMP object is the Profile CMP interface defined by Pro file

Chapter 10
o The values in the attributes of the Profile CMP object returned by getBeforeUp-
dateProfile and getAfterUpdateProfile are the values in the Profile imme -
diately before and after the Profile was updated, respectively. These values may be dif-
ferent from the corresponding attribute values in the Profile obtained from the Profiler
identifier returned by the getProfile method (if the Profile identifier identifies a Pro-
file). The values may be different if the Profile identified by the Profile identifier has
been modified again since the update that was reported by the event.
o The Profile CMP object returned by an invocation of one of these methods is only valid
within the same transaction that the invocation occurred in. (The same event may be re -
fired and processed in a new transaction, if one of these method is invoked to obtain an-
other Profile CMP object, this new Profile CMP object will only be valid within the new
transaction.)
o These method may return null if the relevant profile specification implementation
classes for the profile are not available in the classloader of an SBB which receives this
event. This may occur, for example, if an SBB entity attaches to the Profile Table Activ-
ity of a profile table for which the SBB of the SBB entity has not declared a profile-
spec-ref entry in its deployment descriptor for the profile specification of the profile
table.
10.3.4 Profile Removed Events

The event-definition element for Profile Removed Events is as follows:
<event-definition>
…
<event-type-name> javax.slee.profile.ProfileRemovedEvent </event-type-name>
<event-class-name> javax.slee.profile.ProfileRemovedEvent </event-class-name>
</event-definition>
The ProfileRemovedEvent interface is as follows:

public interface ProfileRemovedEvent {

public Object getRemovedProfile();
}
• The getProfileAddress method returns an Address object identifying the Profile that has
been removed. When an event is fired, the event producer may optionally provide to the event
router a default address that is used to route the event (see Section 8.2.1). In the case of a Profile
Removed Event, the SLEE is the event producer and the default address provided by the SLEE for
the Profile Re moved Event is the address returned by this method.
• The getProfile method returns the Profile identifier of the Profile removed from the Profile
Table. The Profile identifier may or may not identify an existing Profile in the Profile Table. For
example, the Profile identifier may identify a new Profile in the Profile Table if a new Profile has
been added with the same Profile identifier after the previous Profile with same Profile identifier
was removed but before the SLEE delivers the event.
• The getRemovedProfile method returns a read-only Profile CMP object that provides the
content of the Profile when the Profile was removed.

Chapter 10
o The Java type of the Profile CMP object is the Profile CMP interface defined by Profile
o The values in the attributes of the Profile CMP object are the values present in the Profile
immediately before the Profile was removed from the Profile Table. These values may be
different from the attribute values in the Profile obtained from the Profiler identifier re -
turned by the getProfile method (if the Profile identifier identifies a Profile). The
values may be different if the Profile identified by the Profile identifier has been added
after the previous Profile identified by the Profile identifier was re moved.
o The Profile CMP object returned by an invocation of this method is only valid within the
same transaction that the invocation occurred in. (The same event may be re-fired and
processed in a new transaction, if this method is invoked to obtain another Profile CMP
object, this new Profile CMP object will only be valid within the new transaction.)
o This method may return null if the relevant profile specification implementation classes
for the profile are not available in the classloader of an SBB which receives this event.
This may occur, for example, if an SBB entity attaches to the Profile Table Activity of a
profile table for which the SBB of the SBB entity has not declared a profile-spec-
ref entry in its deployment descriptor for the profile specification of the profile table.
10.3.5 ProfileTableActivityContextInterfaceFactory interface

An SBB can obtain a generic Activity Context Interface object of a Profile Table using a Profile-
TableActivityContextInterfaceFactory object. The ProfileTableActivity-
ContextInterfaceFactory object is bound to a SLEE specification defined location in the comp o-
nent environment of every SBB (see Section 13.8).
public interface ProfileTableActivityContextInterfaceFactory {

getActivityContextInterface(ProfileTableActivity tableActivity)
FactoryException;
}
tional semantics, and the common exceptions thrown by a getActivityContext-
Interface method.
10.4 Profile Specification

Each Profile Specification includes:
• A Profile CMP interface.
This interface defines the schema of the Profile Table, i.e. it defines the attributes of each Profile
in the Profile Table. The SBB Developer declares each attribute using a pair of get and set acces-
sor methods in this interfa ce.
• A Profile Management interface, optional.
This interface declares the methods that are made available to management clients. These methods
may include methods declared in the Profile CMP interface and additional SBB Developer de-
Chapter 10
clared management methods (not methods defined in the SLEE specification defined Profile-
Management interface) that interact and manipulate the attributes of a Profile that conforms to
this Profile Specific ation.
• A Profile Management abstract class, optional.
This abstract class implements the Profile CMP interface, the Profile Management interface, and
the ProfileManagement interface. The SBB Developer implements the management methods
declared in the Profile Management interface and the Profile life cycle methods declared in the
ProfileManagement interface in this abstract class. The SLEE implements the get and set ac-
cessor methods of the Profile CMP interface in a derived class of the abstract class when the Pro-
file Specification is deployed. The methods implemented by the SBB Developer can invoke these
accessor methods to manipulate the attributes of a Profile that conforms to this Profile Specifica-
tion.
• A Profile Specification deployment descriptor element.
This element contains sub-elements that identify the above interfaces and abstract class of the Pro-
file Specification, and the attributes that should be indexed or indexed as well as unique.
10.5 Views of a Profile Specification

There are three ways to view a Profile Specification.
• The SBB Developer’s SBB object view.
In this view, the SBB Developer is concerned with the interfaces presented to SBB objects to ac-
cess data in a Profile conforming to the Profile Specification.
• The SBB Developer’s management view.
In this view, the SBB Developer is concerned with the interfaces and classes provided to and used
by the SLEE management system to provision a Profile conforming to the Profile Specification.
• Administrator’s view.
In this view, the Administrator is concerned with the MBean interface derived by the SLEE from
the Profile Specification when the Profile Specification is deployed.
10.5.1 SBB Developer’s SBB object view

The SBB object view consists only of a read-only view of the attributes of the Profile. These attributes are
defined in the Profile CMP interface. The SBB object is only permitted to invoke the get accessor methods
of the Profile CMP interface.
10.5.2 SBB Developer’s management view

The SBB Developer’s management view of a Profile Specification defines the Profile Specification specific
methods that are made visible to management client (see Section 10.5.3 for the Administrator’s view) and
may optionally provide implementations of the Profile Management object life cycle callback methods that
are invoked by the SLEE. A Profile Manage ment object is an object that interacts with the persis tent state
of a Profile on behalf the management client.
• If the SBB Developer defines a Profile Management interface, then the Profile Management inter-
face defines the Profile Specification specific methods that are made visible to management cli-
ents.
• If the SBB Developer does not define a Profile Management interface, then the Profile Manage-
ment interface is the Profile CMP interface. Hence, all get and set accessor methods declared in
the Profile CMP interface are made visible to management clients.
The methods declared in a Profile Management interface are divided into the two following categories:
• CMP field get and set accessor methods.
These methods are declared in the Profile CMP interface. The SBB Developer does not provide
the implementations of these methods in the Profile Management abstract class. The SLEE pro-

Chapter 10
vides the implementations of these methods in a concrete subclass of the Profile Management ab-
stract class.
• Management methods.
These methods are not declared in the Profile CMP interface. These management methods may for
example update a set of Profile attributes in one go or return some result computed from the values
of a set of attributes. The SBB Developer must provide the implementations of these methods in
the Profile Management a bstract class.
The optional Profile Management abstract class implements the following:
• The Profile Management class implements the management methods defined in the Profile Man-
agement interface. If the Profile Management declares any management methods, the SBB Devel-
oper must provide a Profile Management abstract class.
• The Profile Management class also implements the life cycle callback methods that are declared in
the SLEE specification defined ProfileManagement interface. For example, the life cycle
callback methods allow initial values for Profile attributes to be set when the default Profile is cre-
ated, or to perform verification checks on Profile attribute values when the Administrator selects
to commit changes made to a Profile.
Since the management view is dependent on the existence of an SBB object view (if an SBB object view
does not exist there is effectively no Profile attributes to manage for the Profile), the SBB Developer may
only define a management view if an SBB object view is defined. More precisely, a Profile Specification
cannot include a Profile Management interface and/or a Profile Management abstract class if it does not
include a Profile CMP interface. The following table illustrates the allowed combinations.
Profile Profile Man-

Profile CMP Management agement
Combinations interface interface abstract class Comments
All Profile CMP interface accessor

1 X methods are available to manage-
ment clients.
Only Profile CMP interface acces-

sor methods that are also defined in
2 X X the Profile M anagement interface
are available to management cli-
ents.
All Profile CMP interface accessor

methods are available to manage-
3 X X ment clients. The Profile Manage-
ment abstract class implements the
life cycle callback methods.
Only method defined in the Profile

Management interface are avail-
able to management clients. These
method may include Profile CMP
4 X X X accessor methods and management
methods. The Profile Management
abstract class implements the man-
agement methods and the life cycle
callback methods.

Chapter 10
10.5.3 Administrator’s view

An Administrator’s view of a Profile Specification is the Profile Specification’s JMX MBean interface,
known as the Profile MBean interface. The Profile MBean interface is the external management interface
that is visible to external management clients that interact with the Profiles specified by the Profile Specifi-
cation.
The Profile MBean interface is generated by the SLEE when the Profile Specification is deployed from the
methods defined in the Profile Management interface if a Profile Management interface is provided or from
the Profile CMP interface if a Profile Management interface is not provided.
10.6 Profile CMP interface

The Profile CMP interface defines the collection of persistent attributes or CMP fields of the Profile Speci-
fication. All persistent attributes that can be accessed by SBBs must be included in the Profile CMP inter-
face. At deployment time the SLEE implements the Profile CMP interface to provide the mechanism to
support the actual persistence of the data values.
The following are the requirements for the Profile CMP interface:
• The Profile CMP interface must be declared as public.
• CMP fields are defined in the Profile CMP interface by the use of abstract get and set accessor
methods with the following design pattern:
public abstract <attribute type> get<attribute name>();
public abstract void set<attribute name>(<attribute type> value);
o Attribute names must be valid Java identifiers. The first letter of the attribute name in a
get and set accessor method must be capitalized, as determined by
java.lang.Character.isUpperCase. This means that getFoo is legal, while
getfoo is not.
o Each attribute must have both a get and set accessor method defined, and the correspond-
ing types used in the get and set accessor methods must be the same.
o Attribute types must conform to the require ments specified in Section 10.12.
o Neither get nor set accessor methods are permitted to include a throws clause.
• The Profile CMP interface may have super-interfaces, however all super-interfaces are also sub-
ject to the rules for definition of Profile CMP interfaces.
While the Profile CMP interface defines both get and set accessor methods, the current SLEE specification
does not allow an SBB object to change Profile attribute values using the set accessor methods. An SBB
object that attempts to invoke set accessor methods in the Profile CMP interface should expect to receive a
java.lang.UnsupportedOperationException.
10.6.1 Profile refere nces in Profile CMP interface

A Profile may reference other Profiles (or itself) if it has attributes whose Java types are ProfileID, or
Java types that contain ProfileID objects, such as classes that directly or indirectly contain Pro-
fileID objects or ProfileID arrays. The SLEE does not check that the ProfileID objects in the
CMP fields of a Profile re fer to Profiles that exist.
Note: Future versions of the SLEE specification may include deployment descriptors that specify additional
referential integrity constraints or checks for Profile references stored in CMP fields.
10.7 Profile Management interface

The following are the requirements for the SBB Developer defined Profile Management interface:
• The Profile Management interface must be declared as public.

Chapter 10
• The Profile Management interface may extend the Profile CMP interface.
If the Profile Management interface extends the Profile CMP interface, management clients will
be able to invoke the get and set accessor methods defined in the Profile CMP interface to read
and modify all the attributes defined by the Profile CMP interface.
• The Profile Management interface may declare attribute get and set accessor methods.
These methods must be declared in the Profile CMP interface, i.e. the method name, argument and
return types must be the same as declared in the Profile CMP interface and must not have a
throws clause.
• The Profile Management interface may declare management methods.
The following rules apply to management methods:
o Management methods may have any name, but
§ the name must not be the same as any method defined in the javax.sl-
ee.profile.ProfileMBean interface (see Section 10.15.3) or the Profile
CMP interface unless these methods are overloaded, i.e. have different input ar-
guments,
§ the name must not begin with “profile”,
§ the name should not be one of the method names defined in JMX interfaces such
as javax,management,DynamicMBean and javax.management.M-
BeanRegistration.
o Method argument and return types must conform to the requirements specified in Section
10.12.
o Methods may define an arbitrary throws clause.
• The Profile Management interface may have super-interfaces, however all super-interfaces are
also subject to the rules for definition of Profile Management interfaces.
10.8 Profile Management abstract class

The following are the requirements for the Profile Management abstract class:
• The Profile Management abstract class must be declared as public and abstract.
• The Profile Management abstract class implements the following interfaces.
o It must implement the javax.slee.profile.ProfileManagement interface.
o It must implement the Profile CMP interface defined in the Profile Specification, but
must not implement any of the get and set accessor methods defined in the Profile CMP
interface.
o If the Profile Specification defines a Profile Management interface, the Profile Manage-
ment abstract class must implement the Profile Management interface. All management
methods defined in the Profile Management interface must be implemented in the Profile
Management abstract class. These method implementations must be public, and cannot
be static, abstract, or final.
• A Profile Management abstract class that does not implement a Profile Management interface is
limited to implementing Profile life cycle callback methods only as the SLEE implements the
CMP field accessor methods declared in the Profile CMP interface.
• The Profile Management abstract class must have a public constructor that takes no arguments.
• The profileInitialize, profileLoad, profileStore, and profileVerify meth-
ods, defined in the ProfileManagement interface, must be implemented in the Profile Man-
agement abstract class. These method implementations must be public, and cannot be static,
abstract, or final.

Chapter 10
• The isProfileDirty, markProfileDirty and isProfileValid methods must not be

implemented as they are implemented by the SLEE. These three methods are implemented by the
SLEE at deployment time.
• The Profile Management abstract class may have super-classes, however all super-classes are also
subject to the rules for definition of Profile Management abstract classes.
10.9 Profile Management objects

A Profile Management object can be either one of the following objects:
• An object that implements the Profile Management abstract class.
If the Profile Specification defines a Profile Management abstract class (combinations 3 and 4),
then the SLEE extends the Profile Management abstract class and implements the abstract meth-
ods of the Profile Management abstract class. An instance of the derived concrete implementation
class of the Profile Management abstract class is a Profile Management object.
• An object that implements the Profile CMP interface and the ProfileManagement interface.
If the Profile Specification does not define a Profile Management abstract class (combinations 1
and 2), then the SLEE implements a class that implements methods defined in both the Profile
CMP interface and the ProfileManagement interface. An instance of this class is a Profile
Management object.
The SLEE instantiates a Profile Management object to interact with the configuration data maintained in a
Profile. The Profile Management object is the runtime e xecutable object that caches and manipulates the
persistent data in a Profile by invoking the CMP field get and set accessor methods defined in its Profile
CMP interface.
10.9.1 Transient state

A Profile Management object may use instance variables to maintain transient state, or to store values that
depend on the persistent state cached by the CMP fields (or vice-versa),. The profileLoad method (see
Section 10.9.4) can be used by the Profile Management object to resynchronize the values stored in the
instance variables that depend on the persistent state cached by the CMP fields. In general, any transient
state that depends on the persistent s tate cached by the CMP fields should be recomputed during the pro-
fileLoad method. CMP fields whose value depends on transient state stored in instance variables should
have their values set during the profileStore method (see Section 10.9.5). The instance variables of a
Profile Management object are not guaranteed to retain their values after profileStore has returned.
10.9.2 ProfileManagement interface

All Profile Management objects implement the javax.slee.profile.ProfileManagement. This
interface defines various life cycle callback methods, an attribute data verification callback, and a modifica -
tion status flag. The life cycle of a Profile Management object is further discussed in Section 10.16.
The ProfileManagement interface is as follows:
import javax.slee.SLEEException;
public interface ProfileManagement {

public void profileInitialize();
public void profileLoad();
public void profileStore();
public void profileVerify() throws ProfileVerificationException;
public boolean isProfileDirty();
public void markProfileDirty();
public boolean isProfileValid(ProfileID profileID)
throws NullPointerException, SLEEException;
}

Chapter 10
10.9.3 profileInitialize callback method

The profileInitialize method can be used to initialize the initial persistent state of a Profile. It can
be assumed that the Profile has been created before this method is invoked. This method is called once only
when the default Profile (see Section 10.1.4) of a Profile Table is first created. The method is not called
each time a Profile is added to a Profile Table since the initial persistent state of the Profile is copied from
the default Profile of the same Profile Table.
After the SLEE invokes the profileInitialize method on a Profile Management object, it always
invokes the profileStore method on the same Profile Management object, so that the Profile Man-
agement object can write its transient state to its CMP fields. Then, the SLEE invokes the pro-
fileVerify method on the same Profile Management object before the state cached in the CMP fields is
committed. The initial state of a Profile must pass any test implemented in this verification method. If the
initial state does not pass the verification check, the Profile Table cannot be created.
10.9.4 profileLoad callback method

The SLEE invokes the profileLoad method on a Profile Management object when it determines that
the Profile Management object should synchronize its transient state stored in instance values with its CMP
fields. The Profile Management object can expect that the SLEE has loaded its CMP fields just prior to this
invocation, and it should recompute or initialize any transient instance variables that depends on the con-
tents of its CMP fields and is needed or expected during the execution of management methods.
This method runs in a transaction context determined by the SLEE, and will depend on the Administrator
that is accessing the Profile Management object. For example if two Administrators are modifying the same
Profile Management object (via a Profile MBean object) then each user’s interactions with the Profile Man-
agement object will execute in different transaction contexts.
10.9.5 profileStore callback method

The SLEE invokes the profileStore method when it determines that the Profile Management object
should synchronize its CMP fields with the transient state held in its instance variables. Any state held in
instance variables that is required to be persistent must be stored into CMP fields before this method re-
turns. After the profileStore method has returned, the SLEE makes no guarantees regarding the life-
time of the state stored in the instance variables of the Profile Management object.
If the SLEE invokes this method after it invokes the profileInitialize method, then it invokes this
method with the same transaction context as the profileInitialize method. Otherwise, the SLEE
invokes this method after it invokes the profileLoad method and invokes this method with the same
transaction context as the profileLoad method. All management methods or CMP field accesses in-
voked between profileLoad and profileStore are also invoked in the same transaction context.
10.9.6 profileVerify callback method

The SLEE invokes the profileVerify method when the Administrator modifying the Profile Manage-
ment object (via a Profile MBean object) selects to commit changes cached in the Profile Management ob-
ject. The profileVerify method can be used to interrogate the state of the CMP fields to e nsure that it
is valid. If the state of the CMP fields is valid, this method should return silently, otherwise it should throw
a javax.slee.profile.ProfileVerificationException with an appropriate explanatory
message. The throws clause is optional.
The SLEE always invokes the profileStore method before it invokes this method, and it invokes this
method with the same transaction context as the profileStore method.

Chapter 10
10.9.7 isProfileDirty and markProfileDirty methods

Each Profile Management object incorporates a SLEE-implemented modification status or dirty flag. This
flag indicates whether the Profile Management object has been modified since last being committed.
The primary purpose of the dirty flags is to allow the SLEE to determine if an Administrator has changed
the Profile Management objects that cache a Profile, and to provide this status to the Administrator.
• The isProfileDirty method returns the value of the dirty flag.
• The markProfileDirty method explicitly marks a Profile Management object as dirty.
• An SBB Profile Management object is dirty
o if its CMP fields have been modified, or
o if its CMP fields will be modified when it synchronizes the transient state held in its in-
stance variables with its CMP fields (when its profileStore method is invoked).
• The dirty flag of a Profile Management object is
o automatically set to true whenever a CMP field of the Profile Management object is
successfully updated,
o explicitly set to true when the markProfileDirty method is invoked on the Profile
Management object,
o automatically set to false when the state cached in the Profile Management object is
successfully committed.
• The isProfileDirty and markProfileDirty methods run in the same transaction con-
text as the calling management method.
• Since the dirty flag is automatically updated when CMP fields are updated, the markProfile-
Dirty method only has practical use when instance state in the Profile Management object is
updated by a management method defined in the Profile Management interface.
10.9.8 isProfileValid method

The Profile Management object may invoke this method to determine whether the specified profileID
argument actually references a Profile that exists in the SLEE. This method throws a java.lang.Null-
PointerException if the profileID argument is null. This method throws a javax.slee.SL-
EEException if the Profile identifier cannot be validated due to a system-level failure.
10.10 Hiding and renaming Profile CMP interface accessor methods

The SBB Developer can use the Profile Management interface to hide and rename CMP field accessor
methods declared in the Profile CMP interface.
• CMP field accessor method hiding.
The SBB Developer hides a CMP field accessor method by declaring a Profile Management inter-
face that does not extend the Profile CMP interface and only includes in the Profile Management
interface the CMP field accessor methods that should be visible.
• CMP field accessor method renaming.
Accessor method renaming builds on CMP field accessor method hiding. In addition to hiding the
CMP field acessor method, the SBB Developer provides a substitute method with a different
name. The SBB Developer provides the implementation of the substitute method in the Profile
Management abstract class. Typically, the substitute method delegates to the hidden CMP field
accessor method. (The CMP field accessor method is hidden from management clients but re-
mains public in the Profile Management abstract class.)
If only the get accessor method of an attribute is visible (either as result of CMP field accessor method hid-
ing or declaring new management methods that conform to the attribute get accessor pattern), then the at-

Chapter 10
tribute would become visible in Profile MBean interface as a read-only attribute. If only the set accessor
method of an attribute is visible, then the attribute would become write-only in the Profile MBean interface.
10.10.1 Uses
For example, the SBB Developer may hide the CMP field accessor methods of a date attribute and define
alternate methods in the Profile Management interface to read and modify the date attribute. For example,
the date attribute may store a date as the number of days since January 1st , 1970. This date format is not
human Administrator friendly. The SBB Developer can hide the CMP field accessor methods of this attrib-
ute from the Profile MBean interface. It can define a set of new accessor methods in the Profile Manage-
ment interface with date formats that are more human Administrator friendly, such as “MM/DD/YYYY”.
10.11 A Profile Specification example

The Profile CMP interface of an example Foo Profile Specification is as follows:
package com.foobar;
import javax.slee.profile.ProfileID;
public interface FooProfileCMP {

public long getDate();
public void setDate(long date);
// accessor methods to a QOS Profile
// in a separate QOS Profile Table
public ProfileID getQOSProfile();
public void setQOSProfile(ProfileID profileID);
}
The Profile Management interface of this Profile Specification is as follows:

package com.foobar;
public interface FooProfileManagement {

// accessor methods declared in FooProfileCMP
public void setQOSProfile(ProfileID profileID);
// substitute for getDate and setDate
public String getMMDDYYDate();
public void setMMDDYYDate(String date);
}
The Profile Management abstract class of this Profile Specification is as follows:
package com.foobar;
import javax.slee.profile.ProfileManagement;
import javax.slee.profile.ProfileVerificationException;
public abstract class FooProfileManagementImpl

implements ProfileManagement, FooProfileCMP, FooProfileManagement
{
public void profileInitialize() { … }
public void profileLoad() { … }
public void profileStore() { … }
public void profileVerify() throws ProfileVerificationException { … }
public String getMMDDYYDate() { … getDate() … }

public void setMMDDYYDate(String date) { … setDate(…) … }
}
The profile-spec element that describes this Profile Specification is as follows:
<profile-spec>
…
<profile-spec-name> FooProfileSpec </profile-spec-name>

Chapter 10
<profile-spec-vendor> com.foobar </profile-spec-vendor>
<profile-spec-version> 3.1.1 </profile-spec-version>
<profile-classes>
com.foobar.FooProfileCMP
<profile-management-interface-name>
com.foobar.FooProfileManagement
</profile-management-interface-name>
com.foobar.FooProfileManagementImpl
</profile-classes>
…
</profile-spec>
10.12 Java type usage

All attributes, method parameters, and return types that are used in Profile CMP interfaces and Profile
Management interfaces must be legal RMI-IIOP types.
For easy management using even the most basic of management clients or human Ad ministrators, it is also
recommended that the types used in the methods of the Profile CMP interface or the Profile Management
interface that are exposed as Profile MBean interfaces be restricted to the following:
• Java primitive types, or the equivalent object wrappers
• java.lang.String
• One-dimensional arrays of the above types
Any other legal RMI-IIOP type may be used with the caveat that a management client may not be able to
manipulate an attribute or invoke a method that uses them. For complex or composite types it is suggested
that they be decomposed into their primitive components and each primitive component exposed as sepa-
rate manageable attribute in the management view, or a management method in the appropriate Profile
Management interface be provided that takes the primitive components as arguments, composes the com-
posite object, and sets the CMP field with the composite object value.
10.13 Profile Tables referenced by a Service

Each Service may optionally reference the two following Profile Tables.
• A Resource Info Profile Table.
This table contains provisioned data that should be passed to resource adaptor entities when the
Service is in the Active state.
• An Address Profile Table.
This table contains provisioned addresses that may cause new root SBB entities of the Service to
be instantiated (see Section 10.13.2).
10.13.1 Resource Info Profile Table

The main purpose of a Resource Info Profile Table is to contain Service specific information that should be
passed to resource adaptor entities when the Service is in the Active state. A typical use is to set up event
filters in resources or their resource adaptor entities if the default event filter mechanism provided by the
SLEE is not sufficient.
Since this version of the SLEE specification does not specify the contract between resource adaptor entities
and the SLEE, when and how the information is passed between the SLEE and resource adaptor entities is
implementation dependent.
Conceptually, when a Service enters the Active state, the SLEE passes all the information contained in the
Service’s Resource Info Profile Table to the resource adaptor entities instantiated in the SLEE. When a

Chapter 10
Service’s Resource Info Profile Table changes (add a Profile, remove a Profile, or Profile updated), the
SLEE should notify the resource adaptor entities of this change.
Each resource adaptor entity should parse this information and act accordingly if it understands the infor-
mation. For example, the resource adaptor entity may modify event filters or modify its operational behav-
ior.
A Resource Info Profile has a single info attribute. The Java type of this attribute is Java.lang.Str-
ing. Since the format of the information in the info attribute and the resource adaptor entity contract is
not specified in this version of the SLEE specification, the information stored in this attribute is unlikely to
be portable across resource adaptor and SLEE implementations. The Administrator will have to customize
the information stored in Resource Info Profile Tables to the deployment environment.
Note: Two Services may specify incompatible or conflicting information in their Resource Info Profile Ta-
ble. This version of the SLEE specification does not specify how the SLEE or the resource adaptors should
handle this situation.
The Profile CMP interface of the Resource Info Profile Specification is as fo llows:
public interface ResourceInfoProfileCMP {

public String getInfo();
public void setInfo(String s);
}
<profile-spec>
…
<profile-spec-name>
ResourceInfoProfileSpec
</profile-spec-name>
<profile-spec-vendor>
javax.slee
</profile-spec-vendor>
<profile-spec-version>
1.0
</profile-spec-version>
<profile-classes>
javax.slee.profile.ResourceInfoProfileCMP
</profile-classes>
</profile-spec>
10.13.2 Address Profile Table

A Service may optionally reference an Address Profile Table. Any Profile Table that meets the following
requirements can be a Service’s Address Profile Table:
• An Address Profile Table must include an addresses attribute. The Java type of this attribute is
an Address array. (This should not be confused with the address attribute in the ProfileID
class).
• Hence, the Profile CMP interface of the Profile Specification of the Profile Table must include the
following methods:
public Address[] getAddresses();
public void setAddresses(Address[] addresses);
• The addresses attribute must be indexed and unique . This is specified using a profile-
index ele ment in the Profile Specification’s deployment descriptor (see example in Section
10.13.2.2). In addition, the unique attribute of the profile-index element must be “True”.
It is used to enforce the uniqueness of addresses stored in the Address Profile Table.

Chapter 10
Future releases of the SLEE specification are likely to relax the uniqueness requirement of the
addresses attribute.
Typically, each Address Profile in a Service’s Address Profile Table represents a subscriber of the Service.
The addresses attribute contains the subscriber’s address(es).
See how the SLEE uses the Address Profile Table to establish event filters in Section 8.6.1 and to deter-
mine whether new root SBB entities of the Service should be instantiated to handle an event in Section 8.5.
10.13.2.1 Standard Address Profile Specification

The SLEE specification defines a standard Address Profile Specification. The standard Profile Specifica-
tion has the required single addresses attribute.
The Profile CMP interface of the standard Address Profile Specification is as follows:
public interface AddressProfileCMP {

public Address[] getAddresses();
public void setAddresses(Address[] addresses);
}

<profile-spec>
…
<profile-spec-name>
AddressProfileSpec
javax.slee
1.0
<profile-classes>
javax.slee.profile.AddressProfileCMP
</profile-classes>
<profile-index>
addresses
</profile-index>
</profile-spec>
10.13.2.2 A custom Address Profile Specification example

The following example illustrates a custom (i.e. non-standard) Address Profile Specification. The Profile
CMP interface of this custom Address Profile Specification is as follows:
package com.foobar;
import javax.slee.profile.AddressProfileCMP;
public interface BarAddressProfileCMP extends AddressProfileCMP {

public string getFooData();
public void setFooData(String s);
// pointer into a QOSProfile in another Profile Table
public void setQOSProfile(ProfileID p);
}
The Profile Management abstract class of this Profile Specification is as follows:

Chapter 10
package com.foobar;
import javax.slee.profile.ProfileManagement;
import javax.slee.profile.ProfileVerificationException;
public abstract class BarAddressProfileManagementImpl

implements ProfileManagement, BarProfileCMP
{
public void profileInitialize() { … }
public void profileLoad() { … }
public void profileStore() { … }
public void profileVerify() throws ProfileVerificationException {
…
/* check QOS Profile is valid */
… isProfileValid(getQOSProfile()) …
/* check addresses are valid */
…
}
}
<profile-spec>
…
<profile-spec-name>
BarAddressProfileSpec
com.foobar
1.0
<profile-classes>
com.foobar.BarAddressProfileCMP
com.foobar.BarAddressProfileManagementImpl
</profile-classes>
<profile-index>
addresses
</profile-index>
</profile-spec>
10.14 Deployment processing

At Profile Specification deployment time, the SLEE implements the following classes for the Profile Speci-
fication:
• The SLEE implements a class that implements the Profile CMP interface. This class is known as
the Profile CMP implementation class and is for the SBB object view of the Profile Specification.
o The get accessor methods of this class are initia lized to the most recent committed state
and are part of an transactions isolated state. The set accessor methods must throw a
java.lang.UnsupportedOperationException.
• The SLEE implements a class that extends the Profile Management abstract class if one is defined.
Otherwise, if the Profile CMP interface is defined, the SLEE implements a class that implements
the Profile CMP interface and the ProfileManagement interface. This class is known as the
Profile Management implementation class and is for the management view of the Profile Specifi-
cation. A Profile Management object is an instance of this class.
o The SLEE must implement the isProfileDirty and markProfileDirty meth-
ods in this class, with consideration to the rules and semantics given in section 10.9.7.

Chapter 10
o The SLEE must implement the set accessor methods inherited from the Profile CMP in-
terface to return by throwing a javax.slee.profile.Read OnlyProfileEx-
ception if the set accessor methods are invoked on an Profile Management object from
a Profile MBean object that is in a read-only state (see Section 10.16.2), or to set the
value of the dirty flag of a Profile Management object to true if any of the CMP fields
of the Profile Management object have been successfully updated using the set accessor
methods.
o The SLEE implements a Profile MBean class (see Section 10.15).
10.15 Profile MBean

The SLEE implements a Profile MBean class for each Profile Specification. A Profile MBean object allows
an Administrator to access a Profile defined by the Profile Specification. More precisely, the Administrator
invokes the Profile MBean object and the Profile MBean object invokes the Profile Management object that
caches the persistent state of a Profile.
The Profile MBean class may implement any MBean type (e.g. standard, dynamic, model, etc), but must
present an MBean interface to the MBean Server that follows the rules discussed in this section. This
MBean interface is called the Profile MBean interface.
It is the responsibility of the SBB Developer to ensure there are no method naming conflicts that may arise
during the Profile MBean construction. If the SLEE encounters errors caused by duplicate method names,
the SLEE should reject the Profile Specification deployment attempt.
10.15.1 Requirements for the Profile MBean interface

The following are the requirements for the Profile MBean interface:
• The Profile MBean interface must include in its definition a ll the methods defined in the interface
javax.slee.profile.ProfileMBean, either by directly or indirectly inheriting from
ProfileMBean interface or by including the operations defined in the ProfileMBean inter-
face in its dynamic interface.
• If the Profile Specification defines a Profile Management interface, each method defined in the
Profile Management interface must be present with the same name, argument, and return types in
the Profile MBean interface. This method may be a CMP field accessor method or a management
method.
• If the Profile Specification does not define a Profile Management interface, each method defined
in the Profile CMP interface must be present with the same name, argument, and return types in
the Profile MBean interface.
• The throws clause of each CMP field get accessor method that is present in the Profile MBean
interface may include javax.slee.management.ManagementException if necessary.
• The throws clause of each CMP field set accessor method that is present in the Profile MBean
interface must include javax.slee.InvalidStateException, and may include java-
x.slee.management.ManagementException if necessary.
• The throws clause of each management method that is present in the Profile MBean interface
must include javax.s lee.InvalidStateException and javax.slee.pro-
file.ProfileImplementationException, and may include javax.slee.manage-
ment.ManagementException if necessary.
10.15.2 Requirements for the Profile MBean class

The following are the requirements for the Profile MBean class:
• The Profile MBean class must be implemented in accordance with the JMX 1.0 specification.

Chapter 10
• The Profile MBean class implements a standard MBean, a dynamic MBean, or a model MBean
but must present the Profile MBean interface that is constructed using the rules specified in Sec-
tion 10.15.1 to the MBean Server.
• The Profile MBean class must expose get and set accessor methods that follow the design pattern
for managed attributes as attributes, i.e. they must be accessible via both the invoke, getAt-
tribute (for get accessor methods) and setAttribute (for write accessor methods) methods
of the MBean Server.
• The Profile MBean class must implement all the methods defined in the javax.slee.pro-
file.ProfileMBean interface. Section 10.15.3 describes each of these methods.
• The Profile MBean class must support the Profile MBean object life cycle defined in Section
10.16.2. If invocation of a set accessor method or a management method results in javax.sl-
ee.profile.ProfileReadOnlyException being thrown by the Profile Management ob-
ject (for exa mple, because a write operation is attempted on a Profile MBean object that is in the
read-only state), the SLEE translates the exception to a javax.slee.InvalidStateEx-
ception before throwing it to the invoking management client.
• The Profile MBean class must implement all the methods that are included in the Profile MBean
interface. The method implementations may delegate invocations to appropriate methods in the
Profile Management implementation class.
• If the implementation of a management method provided by an SBB Developer throws an excep-
tion, the exception must be wrapped in a javax.slee.profile.Profile Implementa-
tionException and re-thrown to the invoking management client.
• The Profile MBean class may use javax.slee.management.ManagementException to
report errors to the management client when an attempt to access or update persistent CMP fields
fails due to a system-level problem.
10.15.3 ProfileMBean interface

All Profile MBean classes implement the javax.slee.profile.ProfileMBean interface. The
ProfileMBean interface defines the methods that support a transactional life cycle for Profile MBean
objects.
The ProfileMBean interface is as follows:
import javax.slee.InvalidStateException;
import javax.slee.management.ManagementException;
public interface ProfileMBean {

public void editProfile() throws ManagementException;
public void commitProfile() throws ManagementException,
ProfileVerificationException,
InvalidStateException;
public void restoreProfile() throws ManagementException,
public void closeProfile() throws ManagementException,
public boolean isProfileWriteable() throws ManagementException;
public boolean isProfileDirty() throws ManagementException;
}
10.15.3.1 editProfile method

The Administrator invokes the editProfile method to obtain read-write access to the Profile MBean
object (if the Administrator currently has read-only access to the Profile MBean object).

Chapter 10
• The implementation of this method should start a new transaction for the editing session, or per-
form the equivalent function.
• If a system-level failure is encountered during the execution of this method or a concurrent edit of
the same Profile is attempted on a SLEE implementation that does not support concurrent edits
(see Section 10.17.2), the implementation should throw a javax.slee.management.Ma-
nagementException to report the exceptional situation to the A dministrator.
• If the Profile MBean object is already in the read-write state when this method is invoked, this
method has no further effect and returns silently.
10.15.3.2 commitProfile method

Once the Administrator has used the Profile MBean object to make changes to the Profile Management
object that cache the persistent state of a Profile, the Administrator invokes the commitProfile method
to attempt to commit the changes permanently.
• The implementation of this method must invoke the profileVerify method of the Profile
Management object that caches the persistent state of the Profile, and only commit the changes if
the profileVerify method returns without throwing an exception. If the profileVerify
method throws a javax.slee.profile.ProfileVerificationException, the
commit attempt should fail, the exception is forwarded back to the management client, and the
Profile MBean object must re main in the read-write state.
• The implementation of this method must also verify that the constraints specified by the Profile
Specification’s deployment descriptor, such as the uniqueness constraints placed on indexed at-
tributes. The SLEE verifies these constraints after it invokes the profileVerify method of the
Profile Management object. If any constraint is violated, then this method throws a javax.sl-
ee.profile.ProfileVerificationException, the commit attempt fails, and the Pro-
file MBean object must re main in the read-write state.
• If a commit succeeds, the Profile MBean object should move to the read-only state. The SLEE
must also fire a Profile Updated Event if a Profile has been updated (see Section 1.1). The dirty
flag in the Profile Management object must also be set to false upon a successful commit.
• If a commit fails due to a system-level failure, the implementation of this method should throw a
javax.slee.management.ManagementException to report the exceptional situation to
the management client. The Profile MBean object should continue to remain in the read-write
state.
• The execution of the commitProfile method (and profileVerify callback methods of the
Profile Management object) must run in the same transaction context as that begun by the edit-
Profile invocation that initiated the editing session. The transaction should only be committed
if the commitProfile method returns successfully, i.e. without throwing an exception.
• The commitProfile method must throw a javax.slee.InvalidStateException if
the Profile MBean object is not in the read-write state.
10.15.3.3 restoreProfile method

The Administrator invokes the restoreProfile method if the Administrator wishes to discard changes
made to the Profile Management object that caches the persistent state of a Profile.
• The implementation of this method rolls back any changes that have been made to the Profile
Management object since the Profile MBean object entered the read-write state and moves the
Profile MBean object to the read-only state. If the Profile MBean object was returned by the cre-
ateProfile method (see Section 14.11), then no new Profile is created since the transaction
will not commit .

Chapter 10
• The execution of this method must begin in the same transaction context as that begun by the
createProfile or editProfile invocation that initiated the editing session, but must roll
back the transaction before returning.
• The restoreProfile method must throw a javax.slee.InvalidStateException if
the Profile MBean object is not in the read-write state.
10.15.3.4 closeProfile method

The Administrator invokes the closeProfile method when the Administrator no longer requires access
to the Profile MBean object.
• The implementation of this method is free to deregister the Profile MBean object from the MBean
Server.
• The closeProfile method must throw a javax.slee.InvalidStateException if the
Profile MBean object is in the read-write state.
10.15.3.5 isProfileWriteable method

The isProfileWriteable method returns true if the Profile MBean object is in the read-write state,
or false if in the read-only state.
10.15.3.6 isProfileDirty method

The isProfileDirty method returns true if the Profile MBean o bject is in the read-write state and
the dirty flag of the Profile Management object that caches the persistent state of the Profile returns true.
This method returns false under any other situation.
10.16 Life cycles

There are two fundamental life cycles that relate to Profiles. The first is the life cycle that applies to the
existence of the actual Profile and the Profile’s persistent state. The second life cycle applies to Profile
MBean objects.
10.16.1 Life cycle of a Profile

A Profile either exists or does not exist. If a Profile exists, its persistent state exists and is maintained per-
sistently by the SLEE.
A Profile Specification must be deployed before Profile Tables of the Profile Specification can be created.
A Profile cannot exist before the Profile Table that it belongs to is created.
When a Profile Table is created, the default Profile is created and initialized. The default Profile is deleted
when the Profile Table is deleted. Figure 13 illustrates the life cycle of the default Profile of a Profile Table,
and the management callbacks that are made to the Profile Management object that caches the persistent
state of the Profile on life cycle transitions. The callbacks are made within the same (new) transaction con-
text. The transaction commits after the profileVerify callbacks have successfully returned.

Chapter 10
Does Not Exist
1. Profile Table created

2. profileInitialize Profile Table deleted
3. profileStore
4. profileVerify
Exists
Figure 13 Life cycle of the default Profile

A normal (i.e. non-default) Profile is explicitly created and deleted by an Administrator through the man-
agement interface of the SLEE. A new Profile’s persistent state is a copy of the persistent state of the de-
fault Profile. Therefore, the management callbacks are not made when a normal Profile is created. Figure
14 illustrates the life cycle of a normal Profile.
Does Not Exist
XXXProvisioningMBean.addProfile XXXProvisioning.removeProfile
(tableName, uniqueProfileKey) (tableName, uniqueProfileKey)
Exists
Figure 14 Life cycle of a normal Profile
10.16.2 Life cycle of Profile MBean objects

A Profile MBean object is an instance of a Profile MBean and it represents a Profile and allows the Profile
to be accessed by an Administrator. It has access to the Profile Management object that caches the persis-
tent state of the Profile and any other objects that are required by the SLEE to implement functionality of
the Profile MBean object. A Profile MBean object must be registered with the SLEE’s JMX MBean Server
in order to be accessible to management clients.
The JAIN SLEE specification does not dictate when a Profile MBean object or a Profile Management ob-
ject must be created or destroyed. However, an appropriate Profile MBean object must be registered with
the MBean server when the JMX Object Name of a Profile is requested via the ProfileProvision-
ingMBean and may be deregistered when the closeProfile method is invoked on the Profile MBean
object.
When a Profile MBean object is created, the Profile MBean object must portray a read-write view to man-
agement clients. Alternatively, when the editProfile method is invoked on a Profile MBean object, the
Profile MBean object also shifts to the read-write state.

Chapter 10
• If the restoreProfile method is invoked on the Profile MBean object, any changes that have
been made to the Profile Management object that caches the persistent state of the Profile since the
Profile MBean object entered the read-write state must be discarded.
• If instead the commitProfile method is invoked on the Profile MBean object, the profile-
Verify callback method is invoked on the Profile Management object that caches the persistent
data of the Profile. If the verification callback returns without throwing an exception and the Pro-
file MBean object passes additional SLEE implemented verification (such as checking for unique-
ness of “unique” indexed attributes), the changes made to the Profile Management object are
committed and the Profile MBean object moves to the read-only state. If an exception is thrown by
the verification callback, the Profile MBean object remains in the read-write state.
• The SLEE may invoke the profileLoad and profileStore callback methods at any time to
synchronize the transient state held in the Profile Management object with the persistent state
cached in CMP fields. If the Profile MBean object is in the read-write state, then the SLEE in-
vokes the profileLoad and profileStore methods with the same transaction context as
management methods of the Profile Management objects.
Figure 15 illustrates the life cycle of a Profile MBean object. Transitions marked by asterisks (*) are im-
plementation specific and undefined by this specification.
Does Not Exist
* *
profileLoad management method /

callbacks invoked attribute access
Read-Only
on the Profile
Management object
1. profileCommit invoked
profileEdit on the Profile MBean
profileRestore object
invoked on the invoked on the Profile 2. Successful invocation of
Profile MBean object MBean object profileVerify callback on
the Profile Management object
Read-Write
profileLoad profileStore
callback on the Profile callback on the Profile
Management object Management object
management method /
attribute access /
attribute update
Figure 15 Life Cycle of a Profile MBean object.

Chapter 10
10.17 Profile MBean object management

Profile MBean objects do not always have to be registered with the SLEE’s MBean Server. The Adminis-
trator can only access a Profile after it invokes the createProfile, getProfile, and getDe-
faultProfile methods of the ProfileProvisioningMBean interface (see Section 14.11).
Each of these methods returns a suitable JMX Object Name for the appropriate Profile. However, before
returning the Object Name from one of these methods, the SLEE must ensure that the appropriate Profile
exists and the Profile MBean object that represents the Profile is registered with the MBean server.
Once finished with the Profile, the Administrator can invoke the closeProfile method directly on the
Profile MBean object that represents the Profile. This informs the SLEE that the Profile is no longer re-
quired by the Administrator, and the Profile MBean object may be deregistered from the MBean Server if
no other valid references to the Profile MBean object’s Object Name have been given to other Administra-
tors.
After invoking a closeProfile method on a Profile MBean object, the Administrator must assume that
the Object Name reference previously obtained is no longer valid.
10.17.1 Profile editing

When the Administrator invokes the getProfile and getDefaultProfile methods of a Pro-
fileProvisioningMBean object to get access to a Profile (see Section 14.11), the Administrator ini-
tially has read-only access to the Profile after o btaining the Object Name of the Profile MBean object that
represents the Profile from the SLEE. The Administrator invokes the editProfile, commitProfile,
and restoreProfile methods on the Profile MBean object to manage the life cycle of the Profile
MBean object.
When the Administrator creates a new Profile, the Administrator has read-write access to a Profile MBean
object, equivalent to invoking editProfile on the Profile MBean object. The initialattribute values of
the new Profile MBean object are obtained from the default Profile. The SLEE will try to add the new Pro-
file to the Profile Table only after the Administrator invokes the commitProfile method on the Profile
MBean object. This allows the Profile MBean object and the SLEE to verify the contents of new Profile
before adding the Profile to the Profile Table.
10.17.2 Management client isolation

A SLEE implementation may allow two or more sessions to edit a Profile concurrently. If a Profile is edited
simultaneously in two or more separate sessions, the SLEE must ensure that any changes made to the Pro-
file in one session are isolated from (i.e. not visible to) the other sessions. Whether or not concurrent trans-
actions against the profile are able to commit depends on the concurrency control semantics used by the
SLEE implementation, and the semantics of the concurrent access to the profile.
Alternatively, a SLEE implementation may not allow two or more sessions to edit a Profile concurrently. If
this occurs, the editProfile method of the ProfileMBean interface throws a javax.slee.ma-
nagement.ManagementException.
10.18 SBB object view updates

Any changes made to a Profile by an Administrator must not be made visible to SBB objects until the Ad-
ministrator commits these changes and the SLEE commits these changes successfully.

Chapter 11
Usage Parameters
Chapter 11 Usage Parameters

A usage parameter is a parameter that can be updated by an SBB to provide usage information and is acces-
sible by the Administrator through the management interface of the SLEE.
Logically, each usage parameter is addressed by a hierarchically scoped name. The four hierarchically
scoped name components within the fully scoped name are as follows:
• Service name component.
This name component is the top-most scoped name. It identifies the Service that the usage parame-
ter belongs to.
• SBB name component.
This name component is the second-level scoped name. It identifies the SBB within the Service,
identified by the Service name component, which has declared the usage parameter, identified by
the usage parameter name component, in its SBB Usage Parameters interface (see Section 011.2).
• SBB usage parameter set name component.
This name component is the third-level scoped name. It identifies an SBB usage parameter set (see
Section 11.3) accessible by the SBB, identified by the SBB name component, within the Service
identified by the Service name component. This name component is undefined when the usage pa-
rameter identified by the usage parameter name component resides in the SBB’s default usage pa-
rameter set.
• Usage parameter name component.
This name component is the lowest-level scoped name. It identifies a usage parameter declared in
the SBB Usage Parameters interface of the SBB identified by the SBB name component.
11.1 Usage parameter types

There are two types of usage parameters.
• Counter-type usage parameters.
An SBB can increment and decrement the value of a counter-type usage parameter. The Adminis-
trator can get and reset the value of a counter-type usage parameter through the SLEE’s manage-
ment interface.
• Sample-type usage parameters.
The SBB can add sample values to a sample -type usage parameter. The Adminstrator can get the
minimum, maximum, mean, and number of the sample values added to a sample -type usage pa-
rameter and reset the state of the usage parameter through the SLEE’s management interface.
11.2 SBB Usage Parameters interface

The SBB Developer may optionally declare an SBB Usage Parameters interface for an SBB.
• The SBB Usage Parameters interface must be declared as public.
• Each method within the SBB Usage Parameters interface declares a lowest level usage parameter
name relevant to the SBB.
• The SLEE derives the usage parameter type associated with this usage parameter name from the
method name of the declared method.
• A single usage parameter name can only be associated with a single usage parameter type. The
SLEE must check and reject an SBB Usage Parameters interface that declares both an increment
method and a sample method for the same usage parameter name.
• A usage parameter name must be valid Java identifier and begins with a lowercase letter, as de-
termined by java.lang.Character.isLowerCase.

Chapter 11
Usage Parameters
• This interface is optional. If the SBB does not declare any usage parameter names, the SBB De-
veloper does not have to provide an SBB Usage Parameters interface.
11.2.1 Counter-type usage parameter increment method

The SBB Developer declares an increment method to declare the presence of and to permit updates to a
counter-type usage parameter. The method name of the increment method is derived by adding an “incre-
ment” prefix to the usage parameter name. The increment method has the following method signature:
public abstract void increment<usage parameter name>(long value);
• The increment method must be declared as public and abstract.

• The first letter of the usage parameter name is uppercased in the definition of the increment
method.
• The increment method does not have a throws clause.
• This method runs in an unspecified transaction context (see Section 9.7.1). Counter-type usage pa-
rameter updates do not require an active transaction. Counter-type usage parameter updates occur
regardless of the outcome of any transaction active at the time of the update. If multiple SBB ob-
jects update the same usage parameter at the same time these updates should be accumulated as if
the updates were serial.
• The method throws a javax.slee.SLEEException if the requested operation cannot be per-
formed due to a system-level failure.
11.2.2 Sample-type usage parameter method

The SBB Developer declares a sample method to declare the presence of and to permits updates to a sam-
ple-type usage parameter. The method name of the sample method is derived by adding a “sample” prefix
to the usage parameter name. The sample method has the following method signature:
public abstract void sample<usage parameter name>(long value);
• The sample method must be declared as public and abstract.

• The first letter of the usage parameter name is uppercased in the definition of the sample method.
• The sample method does not have a throws clause.
• This method runs in an unspecified transaction context (see Section 9.7.1). Sample-type usage pa-
rameter updates do not require an active transaction. Sample-type usage parameter updates occur
regardless of the outcome of any transaction active at the time of the update. If multiple SBB ob-
jects update the same usage parameter at the same time these updates should be accumulated as if
the updates were serial.
• The method throws a javax.slee.SLEEException if the requested operation cannot be per-
formed due to a system-level failure.
11.2.3 SBB Usage Parameters interface deployment descriptor

If an SBB declares an SBB Usage Parameters interface, the deployment descriptor of the SBB must iden-
tify the SBB Usage Parameters interface. The sbb-usage-parameter-interface e lement of the
SBB deployment descriptor identifies this interface. It contains the following sub-elements:
• An sbb-usage-parameter-interface-name element.
This element identifies the class name of the SBB Usage Parameters interface.

Chapter 11
Usage Parameters
11.2.4 SBB Usage Parameters interface example

In the following example, the FooSbbUsageParameters interface declares two usage parameter
names for counter-type usage para meters and two usage parameter names for sample-type usage parameters
relevant the the Foo SBB.
package com.foobar;
…
public interface FooSbbUsageParameters {
// counter-type usage parameter names
public void incrementFirstCount(long value);
public void incrementSecondCount(long value);
// sample-type usaga parameter names

public void sampleTimeBetweenNewConnections(long value);
public void sampleTimeBetweenErrors(long value);
}
The usage parameter names of the counter-type usage parameters are “firstCount” and “secondCount”. The
usage parameter names of the sample-type usage parameters are “timeBetweenNewConnections” and
“timeBetweenErrors”.
<sbb>
…
<sbb-classes>
…
<sbb-usage-parameters-interface>
<sbb-usage-parameters-interface-name>
com.foobar.FooSbbUsageParameter
</sbb-usage-parameters-interface-name>
</sbb-usage-parameters-interface>
…
</sbb-classes>
…
</sbb>
11.3 SBB usage parameter sets

An SBB may access multiple usage parameters with the same lowest-level usage parameter name comp o-
nent by using multiple SBB usage parameter sets. An SBB usage parameter set is a set that contains a usage
parameter for each usage parameter name declared in the SBB Usage Parameters interface of the SBB.
Each method of the SBB Usage Parameters interface declares the usage parameter name and type of a sin-
gle u sage parameter in this set.
Each SBB usage parameter set has a name. Since a usage parameter name component is scoped within Ser-
vice and SBB name components, the SBB usage parameter set namespace of an SBB within a Service is
independent of the SBB usage parameter set namespaces of other SBBs within the same Service. The SBB
usage parameter set namespace of the SBB within the Service is also independent of the SBB usage p a-
rameter namespaces of the SBB usage parameter set namespaces of the (same or different) SBBs belonging
to other Services.
For example, if Foo SBB is a member of the Bar Service and the Foo SBB declares the example SBB Us-
age Parameters interface in Section 011.2, then each Foo SBB usage parameter set will include two
counter-type usage parameters named “firstCount” and “secondCount” and two sample-type usage parame-
ters named “timeBetweenNewConnections” and “timeBetweenErrors”. If the Foo SBB within the Bar Ser-
vice has an SBB usage parameter set named “GoldSet”, then all the Foo SBB objects within the Bar Ser-
vice use this name to lookup this SBB usage parameter set. SBB objects belonging to other SBBs within
the Bar Service cannot get access to this usage parameter set. SBB objects belonging to other Services also
cannot get access to this usage parameter set.

Chapter 11
Usage Parameters
11.3.1 Default SBB usage parameter set

By default, if an SBB declares an SBB Usage Parameters interface, the SLEE automatically maintains a
default SBB usage parameter set for the SBB in each Service it appears in. The SLEE specification does
not specify the name of the default SBB usage parameter set. The only requirement is that that the name of
the default SBB usage parameter set is not an valid name that can be provided by an Administrator.
11.3.2 Named SBB usage parameter set

In addition to the default SBB usage parameter set created by the SLEE for an SBB within a Service, the
Administrator can create additional SBB usage parameter sets for the same SBB within the same Service.
These Administrator created SBB usage parameter sets must have a name.
• The name of a named SBB usage parameter set may only contain letter or digit characters as de-
fined by java.lang.Character.isLetter and java.lang.Character.isDigit.
Additionally, any other character in the Unicode range 0x0020 -0x007e may be included in a name.
• The name of a named SBB usage parameter set cannot be zero-length.
11.4 Getting access to an SBB usage parameter set

If the SBB Developer declares an SBB Usage Parameters interface, the SBB Developer should also declare
at least one of the get SBB Usage Parameter methods to get access to objects that implement the SBB Us-
age Parameters interface. Each of these SBB Usage Parameters objects represent a single SBB usage pa-
rameter set and each of its increment or sample method manipulate a single counter-type or sample-type
usage parameter in the SBB usage parameter set.
11.4.1 Get SBB Usage Parameter method

There are two forms of get SBB Usage Parameter methods. The first form returns the default SBB usage
parameter set and the second form returns a named SBB usage parameter set. The method signatures of
these methods are as follow:
public abstract <SBB Usage Parameters interface>
getDefaultSbbUsageParameterSet();
public abstract <SBB Usage Parameters interface>
getSbbUsageParameterSet(String name)
throws UnrecognizedUsageParameterSetNameException;
plementation of the get SBB Usage Parameter methods when the SBB is deployed.
• The fully scoped name used to locate an SBB usage parameter set consists of the name of the Ser-
vice that the SBB object invoking this method belongs to, the name of the SBB, and the SBB us-
age parameter set name specified by the name argument (or the default name, if the first method
variant is used).
• This method throws a javax.slee.usage.UnrecognizedUsageParameter SetName-
Exception if the name argument does not identify a named SBB usage parameter set created
by the Administrator.
• The return type must be the SBB Usage Parameters interface of the SBB, or a base interface of the
SBB Usage Parameters interface of the SBB. The SBB uses the returned SBB Usage Parameter
object to update the usage parameters within the SBB usage parameter set represented by the SBB
Usage Parameter object.
• These methods run in an unspecified transaction context (see Section 9.7.1). Getting access to an
SBB Usage Parameter object does not require an active transaction.
• These methods throws a javax.slee.SLEEException if the requested operation cannot be
performed due to a system-level failure. This exception is not declared in the throws clause.

Chapter 11
Usage Parameters
11.4.2 Get SBB Usage Parameter method example

The get SBB Usage Parameter methods for the FooSbbUsageParameter interface may be as follow:
package com.foobar;
…
import javax.slee.usage.UnrecognizedUsageParameterSetNameException;
…
public abstract class FooSbb implements javax.slee.Sbb … {
…
public abstract FooSbbUsageParameter getDefaultSbbUsageParameterSet();
public abstract FooSbbUsageParameter getSbbUsageParameterSet(String name)
throws UnrecognizedUsageParameterSetNameException;
…
}

Chapter 12
Runtime Environment
Chapter 12 Runtime Environment

This chapter defines the application programming interfaces (APIs) that a compliant SLEE must make
available to the instances of SLEE component classes at runtime. These APIs can be used by portable
SLEE components because the APIs are guaranteed to be available in all SLEEs.
This chapter also defines the restrictions that the SLEE vendor can impose on the functionality that it pro-
vides to the SLEE components. These restrictions are necessary to enforce security and to allow the SLEE
to properly manage the runtime environment.
12.1 APIs provided by SLEE

This section defines the minimal runtime environment that a SLEE makes available to the instances of
SLEE component classes. The requirements described here are considered to be the minimal requirements;
a SLEE implementation may choose to provide additional functionality that is not required by the SLEE
specification.
A SLEE must make the following APIs available to the instances of SLEE component classes at runtime:
• Java 2 Platform, Standard Edition, v1.3 (J2SE) APIs
• SLEE 1.0 APIs
• JNDI 1.2 Standard Extension
• JAXP 1.0
• JDBC 2.0 Standard Extension (support for row sets only)
12.1.1 Java 2 APIs

The SLEE must provide the full set of Java 2 Platform, Standard Edition, v1.3 (J2SE) APIs. The
SLEE is not allowed to subset the Java 2 platform APIs. The SLEE is allowed to make certain Java 2 plat-
form functionality unavailable to the instances of SLEE component classes by using the Java 2 platform
security policy mechanism. The primary reason for the SLEE to make certain functions unavailable to these
instances is to protect the security and integrity of the SLEE environment, and to prevent these instances
from interfering with the SLEE’s functions.
The following table defines the Java 2 platform security permissions that the SLEE must be able to grant to
the instances of SLEE component classes at ru ntime. The term “grant” means that the SLEE must be able
to grant the permission, the term “deny” means that the SLEE should deny the permission.
Permission name SLEE policy
java.security.AllPermission deny
java.awt.AWTPermission deny
java.io.FilePermission deny
java.net.NetPermission deny
java.util.PropertyPermission grant “read”, “*”
deny all other
java.lang.reflect.ReflectPermission deny
java.lang.RuntimePermission deny
java.lang.SecurityPermission deny
java.io.SerializablePermission deny
java.net.SocketPermission deny
Some SLEE implementations may allow the Deployer to grant more, or fewer, permissions to the instances
of SLEE component classes than specified in above table. Support for this is not required by the SLEE
specification. SLEE components that rely on more or fewer permissions will not be portable across all
SLEEs.

Chapter 12
Runtime Environment
12.1.2 SLEE 1.0 APIs

The SLEE must implement the SLEE 1.0 interfaces as defined in this specification.
12.1.3 JNDI 1.2

At the minimum, the SLEE must provide a JNDI API name space to the instances of each SLEE comp o-
nent’s classes. The SLEE must make the name space available to an instance when the instance invokes the
javax.naming.InitialContext default (no-arg) constructor.
The SLEE specification does not require that all the SBB components deployed in a SLEE be presented
with the same JNDI API name space. Ho wever, all the instances of the same SBB component’s classes
must be presented with the same JNDI API name space.
12.2 Programming restrictions

This section describes the programming restrictions that an SBB Developer must follow to ensure that a
SLEE (i.e. SBB) component is portable and can be deployed in any compliant SLEE. The restrictions apply
to the implementation of the SBB Developer imple mented methods.
• A SLEE component must not use read/write static fields. Using read-only static fields is allowed.
Therefore, it is reco mmended that all static fields in the classes of the SLEE component be de-
clared as final.
This rule is required to ensure consistent runtime semantics because while some SLEE implemen-
tations may use a single JVM to execute all instances of a SLEE component, others may distribute
the instances across multiple JVMs.
• A SLEE component must not use thread synchronization primitives to synchronize execution of
multiple instances.
Same reason as above. Synchronization would not work if the SLEE distributed multiple instances
across multiple JVMs.
• A SLEE component must not use the AWT functionality to attempt to output information to a dis-
play, or to input information from a keyboard.
Most servers do not allow direct interaction between an application program and a key-
board/display attached to the server system.
• A SLEE component must not use the java.io package to attempt to access files and directories
in the file system.
The file system APIs are not well-suited for SLEE components to access data. SLEE components
should use a resource, such as JDBC, to store data.
• A SLEE component must not attempt to listen on a socket, accept connections on a socket, or use
a socket for multicast.
The SLEE architecture allows an instance of a SLEE component class to be a network socket cli-
ent, but it does not allow it to be a network server. Allowing the instance to become a network
server would conflict with the basic function of the SLEE component that is to process events.
• A SLEE component must not attempt to query a class to obtain information about the declared
members that are not otherwise accessible to the SLEE component because of the security rules of
the Java language. The SLEE component must not attempt to use the Reflection API to access in-
formation that the security rules of the Java programming language make unavailable.
Allowing the SLEE components to access information about other classes and to access the
classes in a manner that is normally disallowed by the Java programming language could com-
promise security.

Chapter 12
Runtime Environment
• A SLEE component must not attempt to create a class loader; obtain the current class loader; set
the context class loader; set security manager; create a new security manager; stop the JVM; or
change the input, output, and error streams.
These functions are reserved for the SLEE. Allowing the SLEE component to use these functions
could compromise security and decrease the SLEE’s ability to properly manage the runtime envi-
ronment.
• A SLEE component must not attempt to set the socket factory used by ServerSocket, Socket, or
the stream handler factory used by URL.
These networking functions are reserved for the SLEE. Allowing the SLEE components to use
these functions could compromise security and decrease the SLEE’s ability to properly manage
the runtime environment.
• A SLEE component must not attempt to manage threads. The SLEE component must not attempt
to start, stop, suspend, or resume a thread; or to change a thread’s priority or name. The SLEE
component must not attempt to manage thread groups.
These functions are reserved for the SLEE. Allowing the SLEE component to manage threads
would decrease the SLEE’s ability to properly manage the runtime environment.
• A SLEE component must not attempt to directly read or write a file descriptor.
Allowing the SLEE component to read and write file descriptors directly could compromise secu-
rity.
• A SLEE component must not attempt to obtain the security policy information for a particular
code source.
Allowing the SLEE component to access the security policy information would create a security
hole.
• A SLEE component must not attempt to load a native library.
This function is reserved for the SLEE. Allowing the SLEE component to load native code would
create a security hole.
• A SLEE component must not attempt to gain access to packages and classes that the usual rules of
the Java programming language make unavailable to the SLEE comp onent.
This function is reserved for the SLEE. Allowing the SLEE component to perform this function
would create a security hole.
• A SLEE component must not attempt to define a class in the javax.slee namespace.
This function is reserved for the SLEE. Allowing the SLEE component to perform this function
would create a security hole.
• A SLEE component must not attempt to access or modify the security configuration objects (Pol-
icy, Security, Provider, Signer, and Identity).
These functions are reserved for the SLEE. Allowing the SLEE component to use these functions
could compromise security.
• A SLEE component must not attempt to use the subclass and object substitution features of the
Java Serialization Protocol.
Allowing the SLEE component to use these functions could compromise security.
• A SLEE component must not attempt to pass this as an argument or method result. Instead of
writing code that uses the this reference and callback methods, an SBB Developer should attach
to Activity Contexts to receive events.
• An SBB component must not modify event objects passed to its event handler methods and must
not hold a reference to the event object, directly or indirectly, after the event handler method re-
turns.

Chapter 12
Runtime Environment
• An SBB component must not modify event objects passed to its fire event methods.
To guarantee portability of the SLEE component’s implementation across all compliant SLEEs, the SLEE
components should be tested using a SLEE with the security settings defined in Section 12.1.1. This table
defines the minimal functionality that a compliant SLEE must provide to the SLEE components at runtime.

Chapter 13
Facilities
Chapter 13 Facilities
Facilit ies are standard functional components provided by the SLEE. The SLEE specification defines the
following standard Facilities:
• Timer Facility (see Section 13.1)
• Alarm Facility (see Section 13.2)
• Trace Facility (see Section 13.4 )
• Activity Context Naming Facility (see Section 13.5)
• Profile Facility (see Section 13.6)
13.1 Timer Facility

SBB entities often need to perform periodic actions, or they need to initiate actions and then check at a later
time to make sure they have been completed. The SLEE provides this function in the Timer Facility.
The Timer Facility manages a number of timers, each of which is independent. A timer may fire zero or
more Timer Events.
The SLEE, together with its execution platform (OS, HW, … etc.) must ensure that logical time always
advances.
13.1.1 TimerID interface

Every timer has a Timer identifier, which is included in every Timer Event that is fired by the Timer Facil-
ity for the timer. The Timer identifier is also used to cancel a timer. The Java interface of a TimerID ob-
ject, which encapsulates a Timer identifier, is as follows.
package javax.slee.facilities;
public interface TimerID {

public int hashCode();
public boolean equals(Object obj);
public String toString();
}
The SLEE provides the actual concrete implementation class of TimerID objects returned by the Timer
Facility. This implementation class must meet the follo wing requirements:
• Be serializable.
This requirement allows SBB objects to store TimerID objects in their CMP fields.
• Implement hashCode.
The actual implementation class of a TimerID object must override the Object.hashCode
method. The new hashCode method does not need to provide hash codes that are unique but
does need to provide hash codes that are well distributed. When different TimerID objects
evaluate to the s ame hash code they are uniquely identified by their equals method. See
• Implement equals.
The actual implementation class of a TimerID object must override the Object.equals
method. The new equals method must ensure that the implementation of the method is refle x-
ive, symmetric, transitive and for any non-null value X, X.equals(null) returns false. See
• Implement toString.
The actual implementation class of a TimerID object must override the Object.toString
method. The new toString method must provide a human readable representation of the

Chapter 13
Facilities
TimerID object. If two TimerID objects represent two different Timer identifiers, the
toString method must return two distinct string representations, i.e. string1.eq uals(st-
ring2) returns false. If two TimerID objects represent the same Timer identifier, the toStr-
ing method must return the same string representation, i.e. string1.eq uals(string2) re-
turns true.
13.1.2 TimerFacility interface

SBB objects access the Timer Facility through a TimerFacility object that implements the Timer-
Facility interface. A TimerFacility object can be found at a SLEE specification defined location
in every SBB’s component environment.
The TimerFacility interface is as follows:
import javax.slee.TransactionRolledbackLocalException;
public interface TimerFacility {

public TimerID setTimer(ActivityContextInterface activity,
Address address,
long startTime,
TimerOptions options)
IllegalArgumentException,
FacilityException;
public TimerID setTimer(ActivityContextInterface activity,
Address address,
long startTime,
long period,
int numRepetitions,
TimerOptions options)
FacilityException;
public void cancelTimer(TimerID timerID)
FacilityException;
public long getResolution()
throws FacilityException;
public long getDefaultTimeout()
throws FacilityException;
}
• All methods of the TimerFacility interface, except for the getResolution method and
the getDefaultTimeout method, are required transactional methods. The getResolution
method and the getDefaultTimeout method are non-transactional.
• The SLEE provides a concrete class implementing the TimerFacility interface.
• The methods of this interface throw the javax.slee.facilities.FacilityException
if the requested operation cannot be completed because of a system-level failure.
13.1.2.1 setTimer methods

The TimerFacility interface defines the methods used to set and cancel timers. Timers are set with the
setTimer methods. Each successful invocation of a setTimer method creates a new timer that has a
unique Timer identifier. This Timer identifier is returned to the caller using a TimerID object.

Chapter 13
Facilities
The setTimer methods take an Activity Context Interface object as an argument. Each of these methods
creates a timer that fires Timer Events on the specified Activity Context. If the Timer Facility creates the
timer successfully, the Timer Facility will reference the provided Activity Co ntext (see Section 7.1.4).
• The Timer Facility releases this reference when the timer is cancelled or after the timer has fired
all its Timer Events. In addition, this Facility also releases all its references to an Activity Context
after the SLEE has delivered an Activity End Event to all SBB entities that are attached to the Ac-
tivity Context and can receive the Activity End Event (see Section 8.5.5). This helps the SLEE re-
claim Activity Contexts.
• This reference may prevent the Activity Context from being reclaimed, especially if the Activity
object that is encapsulated by the Activity Context is not ended implicitly by invoking a method,
or by external events, such as disconnecting from a connection. For example, if the Activity Con-
text of a NullActivity object is referenced and the endActivity method of the NullAc-
tivity object is never invoked, then the Activity Context will never be reclaimed.
Since an event is always fired on an Activity Context and with an optional default address (see Section
8.2.1), the second argument of the setTimer methods is an Address object. This argument provides the
default address and is provided to the SLEE event router when the Timer Facility fires a Timer Event for
the timer. Section 8.5 discusses how the default address provided to the event router influences event rout-
ing.
Each timer has a start time, i.e. the time at which the Timer Facility fires the first Timer Event for this
timer.
A timer can be a periodic timer. The Timer Facility fires Timer Events periodically for a periodic timer.
The Timer Facility fires the first Timer Event for the periodic timer at the specified start time and periodi-
cally fires subsequent Timer Events for the periodic timer at a given interval (or period) thereafter. The
Timer Facility fires Time Events for a periodic timer until the periodic timer is cancelled or until the speci-
fied number of repetitions has been reached.
The following rules apply to the arguments of the setTimer methods.
• The activity argument.
This argument must be a valid Activity Context Interface object. It cannot be null.
• The address argument.
This argument provides the default address and can be null if there is no default address.
• The startTime argument.
This argument specifies the start time of the timer. The start time is specified as the number of
milliseconds since January 1, 1970, 00:00:00 GMT (same as Date.getTime() and Sys-
tem.currentTimeMillis()). The start time of the timer is the time at which the Timer Fa-
cility fires the first Timer Event for the timer. If the specified start time is before the current time,
then the start time is advanced to the current time.
• The period argument.
This argument specifies the period of a repeating timer in milliseconds. It must be greater than
zero.
• The numRepetitions argument.
This argument specifies the number of repetitions for a periodic timer. If zero (0) is specified, the
periodic timer will repeat infinitely.
• The options argument.
This argument specifies the desired behavior of the timer (see Section 13.1.3). It cannot be null.
The timeout value specified by the options argument must be less than or equal to the period
specified by the period argument.
If any of the above arguments are null, the setTimer method throws a java.lang.NullPoint-
erException. If the specified start time is less than zero, the specified period is zero or less, or the time-

Chapter 13
Facilities
out value specified by the options argument is greater than the specified period, then the setTimer
method throws a java.lang.IllegalArgumentException. If the setTimer methods are in-
voked without a valid transaction context and the transaction started for the invocation fails to commit, then
these methods will throw a javax.slee.TransactionRolledbackLocalException.
13.1.2.2 cancelTimer method

The cancelTimer method cancels the timer identified by the timerID argument (which is a TimerID
object), A cancelled timer no longer generates new timer events. The SLEE is not required to remove timer
events fired by the timer before it was cancelled but not yet delivered to SBB entities.
If the timerID arg ument is null, then this method throws a java.lang.NullPointerExcep-
tion. If the timer identified by this argument has already been cancelled or has fired all its Timer Events
(some of these events may have not been delivered), then no action is taken.
If the cancelTimer method is invoked without a valid transaction context and the transaction started for
the invocation fails to commit , then this method will throw a javax.slee.TransactionRolled-
backLocalException.
13.1.2.3 getResolution method

Although the unit for the period of a periodic timer is specified in milliseconds, a Timer Facility implemen-
tation may be limited by the available clock resolution and/or scheduler implementation of the underlying
platform. The approximate timer resolution of the Timer Facility can be obtained via the getResolu-
tion method. This allows SBBs to setup timers that take into account the timer resolution of the Timer
Facility. The returned value is an estimate and may change over time to reflect observed SLEE and system
behavior. Time resolution may be affected by system load.
13.1.2.4 getDefaultTimeout method

The getDefaultTimeout method returns the default timeout value (see Section 13.1.3.4). The default
timeout value may be fixed by the SLEE implementation or may be configurable when the SLEE is in-
stalled or started.
13.1.3 TimerOptions objects

The TimerOptions object argument of a setTimer method specifies the desired behavior of the timer
when the timer is created. The TimerOptions object is used to convey to the Timer Facility the desired
behavior of the timer if there is a SLEE restart or when the Timer Facility cannot fire a Timer Event on
time.
A TimerOptions object is used to specify the following options:
• The persistent option
• The preserveMissed option
• The timeout option.
The TimerOptions class is as follows:
public class TimerOptions implements java.io.Serializable {

// constructors
public TimerOptions() { … }
public TimerOptions(TimerOptions options) { … }
public TimerOptions(boolean persistent, long timeout,
TimerPreserveMissed preserveMissed)
// the persistent option

Chapter 13
Facilities
public boolean isPersistent() { … }
public void setPersistent(boolean persistent) { … }
// the preserveMissed option

public TimerPreserveMissed getPreserveMissed() { … }
public void setPreserveMissed(TimerPreserveMissed preserveMissed)
throws NullPointerException {…}
// the timeout value

public long getTimeout() { … }
public void setTimeout(long timeout)
}
The default constructor constructs a TimerOptions object with the persistent option set to false,
the preserveMissed option set to TimerPreserveMissed.LAST, and the timeout option to
zero (0).
13.1.3.1 TimerPreserveMissed objects

The TimerPreserveMissed class defines an enumerated type for the preserveMissed options
supported by the Timer Facility. A singleton instance of each enumerated value is guaranteed (via an im-
plementation of the readResolve method, see java.io.Serializable for more details), so that
equality tests using == are always evaluated correctly. For convenience, an integer representation of
TimerPreserveMissed objects is also available.
The following singleton TimerPreserveMissed objects define the valid arguments that may be pro-
vided to methods that take a TimerPreserveMissed object as argument and may be returned by meth-
ods that return TimerPreserveMissed objects.
• ALL
• NONE
• LAST
The public content of the TimerPreserveMissed class is as follows:
public final class TimerPreserveMissed implements java.io.Serializable {

// singletons
public static final TimerPreserveMissed NONE …;
public static final TimerPreserveMissed ALL …;
public static final TimerPreserveMissed LAST …;
public static final int PRESERVE_NONE …;
public static final int PRESERVE_ALL …;
public static final int PRESERVE_LAST …;
// methods
public boolean isNone() { … }
public boolean isAll() { … }
public boolean isLast() { … }
public static TimerPreserveMissed fromInt(int option)

}
• Each of the is<Option> methods determines if this TimerPreserveMissed object repre-
sents the <OPTION> option, and is equivalent to (this == <OPTION>). For example, the
isNone method determines if this TimerPreserveMissed object represents the NONE op-
tion and is equivalent to (this == NONE).

Chapter 13
Facilities
• The fromInt and toInt methods allow conversion between the TimerPreserveMissed
object form and numeric form.
• The fromInt method throws a java.lang.IllegalArgumentException if the op-
tion argument is not one of the three integer representations.
13.1.3.2 persisten t option

This is a boolean option. If enabled (true), the timer is reinstated when the SLEE restarts after a complete
shutdown (either due to catastrophic failure or operator shutdown). If disabled (false), the timer is can-
celled and no further Timer Events will be fired by the timer.
Even though a timer is persistent, its Timer Events cannot be fired when the SLEE is not running. Depend-
ing on the preserveMissed option, Timer Events that would have been fired when the SLEE is not
running may be fired when t he SLEE is restarted.
13.1.3.3 preserveMissed option

This option specifies which and whether Timer Events will be fired when the Timer Facility cannot fire one
or more of a timer’s Timer Events on time. A Timer Event is not on time (or is late) if the Timer Facility
cannot fire the Timer Event by (scheduled time + timeout value) (see Section 13.1.3.4).
Under normal conditions and expected workload, a SLEE and its Timer Facility should be able to fire
Timer Events on time. However, under overload conditions or when the SLEE is not running, the SLEE
Timer Facility may not be able to fire Timer Events on time.
The following three behaviors can be specified:
• ALL
This option tells the Timer Facility to fire all of the timer’s Timer Events no matter how late they
are. It is useful to application code that depends on the total number of Timer Events received.
• NONE
This option tells the Timer Facility not to fire the timer’s Timer Events that are late. It is useful to
application code that does not care for late Timer Events.
• LAST
This option tells the Timer Facility to fire only the timer’s most recent Timer Event. The most re-
cent Timer Event may be the last in a series of late Timer Events or it may be the most recent on-
time event following a series of late Timer Events. The Timer Facility does not fire earlier unfired
Timer Events that were late except the most recent scheduled Timer Event. This behavior is useful
to application code that would like to be notified when there is at least one late Timer Event but
does not care to receive all outstanding late Timer Events.
The TimerOptions class will throw a javax.lang.NullPointerException if a null value is
provided to its setPreserveMissed or constructor methods.
13.1.3.4 The timeout option

This option specifies a timeout value in milliseconds. The Timer Facility uses this value to determine if a
Timer Event is considered to be late or on time. A Timer Event is late if the Timer Facility cannot fire the
Timer Event by (scheduled time + timeout value). A Timer Event that is fired on time may not be delivered
on time to an SBB entity because the Timer Event may be delayed in the SLEE's event queue or delayed by
SBB entities with higher priorities.
For a periodic timer, the specified timeout value must be no greater than the period (or repetition interval)
of the periodic timer. A zero timeout value specifies the default timeout value (see Section 13.1.2.4) as the
timeout value if the period is more than the default timeout value. Otherwise, a zero timeout value specifies
the p eriod as the timeout value.

Chapter 13
Facilities
The Timer Facility should adjust timeout values that are smaller than the current timer resolution to the
current timer resolution, or the specified period (for periodic timers only), whichever is less. This avoids
dropping Timer Events as a result of insufficient timer resolution (see Section 13.1.6).
The TimerOptions class will throw a java.lang.IllegalArgumentException if a negative
timeout value is provided to its setTimeout or constructor methods. Furthermore, if the timeout value
specified by the options argument to a setTimer method is more than the period argument of the
setTimer method, the Timer Facility will also throw an IllegalArgumentException.
13.1.4 Delays in delivering Timer Events

The Timer Facility is only concerned with whether a Timer Event is fired on time. Although the Timer Fa-
cility may fire a Timer Event on time, an SBB entity may not receive the Timer Event on time because of
delays in the SLEE event router or because a higher priority SBB entity may have taken a long time to
process the Timer Event.
It is possible to have multiple Timer Events belonging to the same timer queued in the SLEE’s event queue
for delivery. In some cases, these Timer Events may not be delivered in a timely ma nner. The SLEE Timer
Facility is not aware of this condition and does not provide an option to collapse multiple outstanding
Timer Events in the SLEE’s event queue (similar to the TimerPreservedMissed.LAST option). This
option was considered but not adopted because this option would require the Timer Facility to keep track
of fired Timer Events. This would complicate implementations of the Timer Facility and consume more
system resources.
13.1.5 Timer Events

The event-definition element for Timer Events is as follows:
<event-definition>
…
<event-type-name> javax.slee.facilities.TimerEvent </event-type-name>
<event-class-name> javax.slee.facilities.TimerEvent </event-class-name>
</event-definition>
The TimerEvent interface is as follows:
public interface TimerEvent {

public TimerID getTimerID();
public long getScheduledTime();
public long getExpiryTime();
public long getPeriod();
public int getNumRepetitions();
public int getRemainingRepetitions();
public int getMissedRepetitions();
}
Each TimerEvent object contains:
• A TimerID object attribute.
This attribute contains the Timer identifier returned by the setTimer method used to create the
timer.
• A scheduledTime attribute.
This attribute contains the time that the SLEE Timer Facility is scheduled to fire the Timer Event,
also known as the scheduled time of the Timer Event. This is the time at which the Timer Event is
expected to fire (assuming no latencies, i.e. a perfect system).

Chapter 13
Facilities
o For a non-periodic timer or the first Timer Event of a periodic timer, the scheduled time
of the Timer Event is the start time specified by the startTime argument of the set-
Timer method.
o For subsequent Timer Events of a periodic timer, the scheduled time of the Timer Event
is the scheduled time of the previous repetition plus the period of the timer (as specified
by the period argument of the setTimer method).
• An expiryTime attribute.
This attribute contains the time that the SLEE Timer Facility actually fired the Timer Event, also
known as the actual expiry time of the Timer Event. This is the time at which the SLEE considers
the event ready to enqueue the Timer Event into the SLEE’s event queue.10
o The Timer Facility provides an estimate of the expected maximum difference between
scheduled and actual expiry times via the getResolution method of the Timer-
Facility interface. This estimate may change over time to reflect current SLEE be-
havior.
• A period attribute.
This attribute contains the repetition period, as specified by the period argument of the set-
Timer method used to create the timer. A non-periodic timer has a period of Long.MAX_VA-
LUE.
• A numRepetitions attribute.
This attribute contains the number of repetitions requested, as specified by numRepetitions
argument of the setTimer method used to create the timer. Its value is zero (0) for a periodic
timer that repeats infinitely and one (1) for a non-repeating timer.
• A remainingRepetitions attribute.
This attribute contains the number of outstanding repetitions, i.e. the potential n umber of Timer
Events that the Timer Facility will fire in the future for this timer. Its value is Long.MAX_VALUE
for an infinitely repeating periodic timer and zero (0) for a non-periodic timer. Otherwise, its value
is numRepetitions minus the repetition number of this Timer Event for a finite repeating pe-
riodic timer.
• A missedRepetitions attribute.
This attribute contains the number of missed repetitions between the last Timer Event and this
Timer Event.
13.1.6 Desired Timer Facility behavior and Timer Facility pseudo code
The Timer Facility implementation must implement the behavior described below.
• The Timer Facility should aim to fire Timer Events with an actual expiry time as close as the
scheduled time as practical.
• The Timer Facility may fire Timer Events with an actual expiry time that is before the scheduled
time. However it should not fire timer events with an actual expiry time that is less than (sched-
uled time – timer resolution11 ). As timer resolution may change over time, users of the Timer Fa-
cility cannot rely on this behavior being strictly followed.
• The Timer Facility must consider all Timer Events where actual expiry time is greater than
(scheduled time + timeout 12 ) as late when timeout is greater than timer resolution. Late Timer
10
The Timer Facility may not actually enqueue the Timer Event if it is marked as late or discarded under the TimerPreserve-
Missed.NONE or TimerPreserveMissed.LAST options.
11
The getResolution method of the TimerFacility interface returns the timer resolution.
12
The timeout value is specified by the timeout attribute of the TimerOptions object originally passed to the setTimer
method.
Chapter 13
Facilities
Events are handled according to the preserveMissed option in the TimerOptions object
originally passed to the setTimer method.
The following pseudo code illustrates the desired behavior of the Timer Facility. The following pseudo
code is periodically executed for each active timer.
// timer is the timer object currently being examined.
// timer.scheduleTime is time that the Timer Event is scheduled to fire.
// timer.timeout is timeout for this timer (from TimerOptions).
// timer.numRepetitions is the total repetitions for this timer, 0 if infinite,
// 1 if non-periodic.
// timer.remainingRepetiton is the remaining repetition count, initially Long.MAX_VALUE
// for infinite periodic timers, timer.numRepetitions
// otherwise.
// timer.period is the timer period (Long.MAX_VALUE if non-periodic).
// timer.missed is the counter of undelivered late events.
//
// Tres is the current timer resolution.
// Tsys is the current system time.
// Tdto is the current default time out
// Tfire is the "fire before" time; all Timer Events scheduled
// before this time are candidates for firing.
//
// Tsys <= Tfire <= Tsys + Tres
// Tres <= Tdto
//
// Timer Events fired are given with scheduled and actual expiry times, and for periodic
// timers, number of missed repetitions. Other attributes of the Timer Event can
// be inferred from current timer state.
if TimerOptions.preserveMissed == TimerPreserveMissed.ALL then

while timer.scheduleTime < Tfire and timer.remainingRepetitions > 0 do
fire event with (
event.scheduledTime = timer.scheduleTime,
event.expiryTime = Tsys,
event.missedRepetitions = 0)
if timer.numRepetitions != 0 then
timer.remainingRepetitions -= 1
endif
timer.scheduleTime += timer.period
endwhile
else
if timer.timeout == 0 then
timeout = Tdto
else
timeout = timer.timeout
endif
timeout = minimum(maximum(timeout, Tres), timer.period)
if TimerOptions.getPreserveMissed == TimerPreserveMissed.NONE then
if timer.remainingRepetitions == 1 and timeout < Tres then
// period goes to infinity for last Timer Event,
// need to change timeout value for cases
// influenced by period
timeout = Tres
endif
if Tsys <= timer.scheduleTime + timeout then
fire event with (
event.scheduledTime = timer.scheduleTime,
event.missedRepetitions = timer.missed)
timer.missed = 0
else
timer.missed += 1
endif
endif

Chapter 13
Facilities
endwhile
else if TimerOptions.getPreserveMissed == TimerPreserveMissed.LAST then
// Count missed events.
// Preserve the last missed event for firing in the second loop.
while timer.scheduleTime + period < Tfire and
Tsys > timer.scheduleTime + timeout and
timer.remainingRepetitions > 1 do
timer.missed += 1
endif
endwhile
// Fire the last missed event preserved above (if any) and
// any on-time events.
fire event with (
event.scheduled = timer.scheduleTime,
event.missedRepetitions = timer.missed)
timer.missed = 0
endif
endwhile
endif
endif
if timer.numRepetitions != 0 and timer.remainingRepetitions == 0 then
cancel timer
endif
13.2 Alarm Facility

SBB components use the Alarm Facility to generate alarm notifications intended for consumption by man-
agement clients external to the SLEE. For example, these management clients may be a network manage-
ment console or a management policy engine. In any case, the management client is responsible for regis-
tering to receive alarm notifications generated by the Alarm Facility through the external management in-
terface of the Alarm Facility (see Section 14.12 ). The management client may optionally provide notifica-
tion filters so that only the alarm notifications that the management client would like to receive are trans-
mitted to the management client. These notification filters reduce alarm re lated network traffic and the
processing that the management client has to perform to filter unwanted alarm notifications.
The external management interface of the Alarm Facility is defined by the AlarmMBean interface. Each
alarm notification generated by the Alarm Facility is emitted through an AlarmMBean object as an
AlarmNotification object. See Section 14.12 for detailed description of the AlarmMBean interface
and the AlarmNotification class.
The Alarm Facility may be used by other alarm sources within the SLEE to generate alarm notifications.
These alarm sources include the various subsystems and Facilities of the SLEE, and resource adaptors. The
SLEE specification does not define the interface that these alarm sources use to emit alarm notifications.
However, each alarm notification is emitted through the same AlarmMBean object and as an AlarmNo-
tification object.
Even though notification filters can be used to limit the number of redundant alarm notifications, and to
suppress transient alarms that clear up spontaneously, alarm sources should use discretion in issuing alarm
notifications, because the notification filters apply to all alarm notifications, and cannot easily take into
account alarm source specific knowledge (beyond the information included in each alarm notification).
Furthermore, the notification filter is coupled with an AlarmMBean object in the management subsystem
of the SLEE and not the AlarmFacility object used to emit the alarm notification. The SLEE may have
to incur some processing overhead to propagate the alarm notification from the AlarmFacility object
to the management subsystem of the SLEE.
Chapter 13
Facilities
13.2.1 AlarmFacility interface

SBB objects access the Alarm Facility through an AlarmFacility object that implements the Alarm-
Facility interface. An AlarmFacility object can be found at a SLEE specification defined location
The AlarmFacility interface is as follows:
import javax.slee.ComponentID;
import javax.slee.UnrecognizedComponentException;
public interface AlarmFacility {

public void createAlarm(ComponentID componentID,
Level level,
String alarmType,
String message,
long timestamp)
UnrecognizedComponentException,
FacilityException;
public void createAlarm(ComponentID componentID,
Level level,
String alarmType,
String message,
Throwable cause,
long timestamp)
FacilityException;
}
• All methods of the AlarmFacility interface are non-transactional methods.

• The SLEE provides the concrete implementation class of an AlarmFacility object. This im-
plementation class implements the AlarmFacility interface.
13.2.1.1 createAlarm method

There are two createAlarm method. A createAlarm method is used to emit an alarm notification. It
takes the following arguments:
• The componentID argument.
This argument specifies the component that is emitting the alarm notification. It is propagated as
the alarmSource attribute of an AlarmNotification object (see Section 14.12.2).
• The level argument.
This argument takes a Level object that specifies the alarm level of the alarm notification. All
the Level objects defined in Section 13.2.2 can be specified except the Level.OFF object.
• The alarmType argument.
This argument specifies the type of alarm being generated. It will be included in the AlarmNo-
tification object emitted by the AlarmMBean object for the alarm notification. A manage-
ment client can use the alarm type of the AlarmNotification object to filter the alarm notifi-
cation. See Section 13.7 for the recommended format of the alarm type string.
• The message argument.
This argument specifies the message that will be placed into the message attribute of the
AlarmNotification object emitted by the AlarmMBean object for the alarm notification.
The AlarmNotification object inherits its message attribute from the standard JMX No-
tification class.

Chapter 13
Facilities
• The optional cause argument.

This argument is typically used to propagate an exception in the alarm notification.
• The timestamp argument.
This argument specifies the timestamp that will be placed into the timestamp attribute of the
AlarmNotification object emitted by the AlarmMBean object for the alarm notification.
The AlarmNotification object inherits its timestamp attribute from the standard JMX
Notification class.
The createAlarm method throws a java.lang.NullPointerException if any of the arguments
are null. It throws a java.lang.IllegalArgumentException if the specified alarm level is
Level.OFF. The createAlarm method throws a javax.slee.UnrecognizedComponentEx-
ception if the componentID argument is invalid. The createAlarm method throws the java-
x.slee.facilities.FacilityException if the requested operation cannot be completed be-
cause of a system-level failure.
13.2.2 Implementation recommendation

The current version of the SLEE specification is designed to be implementable on J2SE 1.3 and J2EE 1.3.
As a result, it does not explicitly require the use of the Java Logging APIs (that are included in J2SE 1.4
and J2EE 1.4) for the implementation of the Alarm Facility or as a possible replacement for the Alarm Fa-
cility.
When possible, the SLEE specification recommends that the Alarm Facility be imple mented using the Java
Logging APIs. For example, the Alarm Facility may be implemented using one or more Loggers and Han-
dlers. An implementation based on the Java Logging APIs is likely to enable the Administrator to have
more control over alarm logging and propagation than provided by the Alarm Facility.
A future SLEE specification will very likely formalize the mapping between the Alarm Facility and the
Java Logging APIs. In the longer term, the Alarm Facility may even be deprecated if and after most SLEE
components have migrated from the Alarm Facility to the Java Logging APIs.
13.3 Level objects

The Level class defines an enumerated type for the levels supported by the Alarm Facility and the Trace
Facility. A singleton instance of each enumerated value is guaranteed (via an implementation of the read-
Resolve method, see java.io.Serializable for more details), so that equality tests using == are
always evaluated correctly. For convenience, an integer representation of Level objects is also available.
The following singleton Level objects define the valid arguments that may be provided to methods that
take a Level object as argument and may be returned by methods that return Level objects. The least
severe alarm or trace levels are listed first.
• FINEST
• FINER
• FINE
• CONFIG
• INFO
• WARNING
• SEVERE
The public contents of the Level class is as follows:
public final class Level implements java.io.Serializable {

// singletons

Chapter 13
Facilities
public static final Level FINEST …;
public static final Level FINER …;
public static final Level FINE …;
public static final Level CONFIG …;
public static final Level INFO …;
public static final Level WARNING …;
public static final Level SEVERE …;
public static final Level OFF …;
public static final int LEVEL_FINEST …;
public static final int LEVEL_FINER …;
public static final int LEVEL_FINE …;
public static final int LEVEL_CONFIG …;
public static final int LEVEL_INFO …;
public static final int LEVEL_WARNING …;
public static final int LEVEL_SEVERE …;
public static final int LEVEL_OFF …;
// methods
public boolean isFinest() { … }
public boolean isFiner() { … }
public boolean isFine() { … }
public boolean isConfig() { … }
public boolean isInfo() { … }
public boolean isWarning() { … }
public boolean isSevere() { … }
public boolean isOff() { … }
public boolean isHigherLevel(Level other)

throws NullPointerException { … }
public static Level fromInt(int level)
}
• Management clients use the Level.OFF object to specify maximum filtering.

• The isHigherLevel method returns true if the level represented by this Level object is
higher or more severe than the level specified by Level object passed as the other argument.
For the purpose of this comparison, OFF has a higher level than SEVERE, i.e. when OFF is speci-
fied in an alarm filter (see Section 14.12.3), no alarms at a lower level than OFF, which is all
alarms, will be emitted. It throws a java.lang.NullPointerException if the other a r-
gument is null.
• Each of the is<Level> methods determines if this Level object represents the <LEVEL>
level, and is equivalent to (this == <LEVEL>). For example, the isSevere method deter-
mines if this Level object represents the SEVERE alarm level and is equivalent to (this ==
SEVERE).
• The fromInt and toInt methods allow conversion between the Level object form and nu-
meric form.
• The fromInt method throws a java.lang.IllegalArgumentException if the level
argument is not one of the eight integer representations.
13.4 Trace Facility

SBBs use the Trace Facility to generate trace messages intended for consumption by external management
clients, such as a network management console or a management policy engine. In any case, the manage-
ment client is responsible for registering to receive trace messages generated by Trace Facility through the
external management interface of the Trace Facility (see Section 14.13). The manage ment client can filter
trace message in the following two ways:

Chapter 13
Facilities
• The external management interface of the Trace Facility provides a method to set the trace filter
level for a Service or an SBB. Only trace messages that are emitted for a component (Service or
SBB) with an equal or higher trace level than the component’s trace filter level will be accepted
and transmitted by the Trace Facility. The management client can use this management interface
to set the trace filter levels for various Services or SBBs. SBB objects can obtain the trace filter
level set by the management client from the Trace Facility. This allows these SBB objects to not
generate trace messages whose trace level is below the trace filter level set by the management cli-
ent.
• The management client can optionally use filters to filter trace messages so that only the trace
messages that the management client would like to receive are transmitted to the management cli-
ent. These filters reduce trace message related network traffic and the processing that the ma n-
agement client has to perform to filter unwanted trace messages.
The external management interface of the Trace Facility is defined by the TraceMBean interface. Each
trace message transmitted by the Trace Facility is emitted through a TraceMBean object as a TraceNo-
tification object. See Section 14.13 for detailed description of the TraceMBean interface and the
TraceNotification class.
The Trace Facility may be used by other entities within the SLEE to generate trace messages. These entities
include the various subsystems and Facilities of the SLEE, and resource adaptors. The SLEE specification
does not define the interface that these entities use to emit trace messages. However, each trace message is
emitted through the same TraceMBean object and as a TraceNotification object.
13.4.1 TraceFacility interface

SBB objects access the Trace Facility through a TraceFacility object that implements the Trace-
Facility interface. A TraceFacility object can be found at a SLEE specification defined location
The TraceFacility interface is as follows:
public interface TraceFacility {

public Level getTraceLevel(ComponentID componentID)
FacilityException;
public void createTrace(ComponentID componentID,
Level level,
String messageType,
String message,
long timestamp)
FacilityException;
public void createTrace(ComponentID componentID,
Level level,
String messageType,
String message,
Throwable cause,
long timestamp)
FacilityException;
}

Chapter 13
Facilities
• All methods of the TraceFacility interface are non-transactional methods. The effects of op-
erations invoked on this facility occur irregardless of the state or outcome of any enclosing trans-
action.
These methods are non-transactional because trace messages emitted from within a transaction
should not be “discarded” if the transaction aborts. In fact, SBBs should use trace messages to
document any unexpected occurrences, including the occurrences that lead to transaction roll-
backs.
• The SLEE provides the concrete implementation class of a TraceFacility object. This im-
plementation class implements the TraceFacility interface.
13.4.1.1 getTraceLevel method

The getTraceLevel method takes the following argument:
This argument specifies the SLEE component whose trace filter level should be returned.
The getTraceLevel method throws a java.lang.NullPointerException if the componen-
tID argument is null. The getTraceLevel method throws a javax.slee.Unrecognized-
ComponentException if the componentID argument does not specify a component recognized by
the SLEE.
13.4.1.2 createTrace methods

There are two createTrace methods. A createTrace method is used to emit a trace message. It
takes the following arguments:
This argument specifies the component that the trace message is emitted for. Typically, the caller
of this method determines whether the trace message is emitted for a Service or an SBB by provid-
ing a ServiceID object or an SbbID object for this argument. The SbbID object that identifies
an SBB and the ServiceID object that identifies a Service can be found in an SbbContext
object. This argument is propagated as the messageSource attribute of a TraceNotifica-
tion object (see Section 14.13.2).
• The level argument.
This argument takes a Level object that specifies the trace level of the trace message. All the
Level objects defined in Section 13.2.2 can be specified except the Level.OFF object. If the
specified trace level is equal or above the trace filter level set for the component identified by the
componentID argument, the Trace Facility will accept the trace message and propagate the
trace message by emitting a TraceNotification object from a TraceMBean object. Other-
wise, the specified trace level is below the trace filter level set for the component identified by the
componentID argument, the Trace Facility will not propagate the trace message any further.
• The messageType argument.
This argument specifies the message type that will be included in the TraceNotification
object emitted by the TraceMBean object. A management client can use the message type of the
TraceNotification object to filter the trace message. See Section 13.7 for the recommended
format of the message type string.
• The message argument.
This argument specifies the message that will be placed into the message attribute of the Tra-
ceNotification object emitted by the TraceMBean object for the trace me ssage. The Tra-

Chapter 13
Facilities
ceNotification object inherits its message attribute from the standard JMX Notifica-
tion class.
• The optional cause argument.
This argument is typically used to propagate an exception in the trace message.
• The timestamp argument.
This argument specifies the timestamp that will be placed into the timestamp attribute of the
TraceNotification object emitted by the TraceMBean object for the trace message. The
TraceNotification object inherits its timestamp attribute from the standard JMX Noti-
fication class.
The createTrace method throws a java.lang.NullPointerException if any of the arguments
are null. It throws a java.lang.IllegalArgumentException if the specified trace level is
Level.OFF. The createTrace method throws a javax.slee.UnrecognizedComponent-
Exception if the componentID argument does not specify a component recognized by the SLEE.
13.4.2 Implementation recommendation

The current version of the SLEE specification is designed to be implementable on J2SE 1.3 and J2EE 1.3.
As a result, it does not explicitly require the use of the Java Logging APIs (that are included in J2SE 1.4
and J2EE 1.4) for the implementation of the Trace Facility or as a possible replacement for the Trace Facil-
ity.
When possible, the SLEE specification recommends that the Trace Facility be imple mented using the Java
Logging APIs. For example, the Trace Facility may be implemented using one or more Loggers and Han-
dlers. An implementation based on the Java Logging APIs is likely to enable the Administrator to have
more control over trace logging and propagation than provided by the Trace Facility.
A future SLEE specification will very likely formalize the mapping between the Trace Facility and the Java
Logging APIs. In the longer term, the Trace Facility may even be deprecated if and after most SLEE com-
ponents have migrated from the Trace Facility to the Java Logging APIs.
13.5 Activity Context Naming Facility

The Activity Context Naming Facility provides a global flat namespace for naming Activity Contexts. It
allows an SBB object to bind a name to an Activity Context, and other SBB objects to lookup the Activity
Context by this name. An Activity Context may be bound to zero or more names.
This Facility allows multiple SBB entities that have been created in response to initial events on different
Activities (thus have different Activity Contexts) to converge on a “shared” Activity Context, so that these
SBB entities can signal each other by firing events on the shared Activity Co ntext and share common state
by reading and modifying attributes.
SBBs that use this Facility are responsible for choosing unique names to avoid unintentional name con-
flicts.
When an Activity Context is bound to at least one name, the Activity Context Naming Facility maintains a
reference to the Activity Context. It releases this reference when the Activity Context is no longer bound to
any names. This occurs when the unbind method of this Facility is invoked to unbind the only name
bound to the Activity Context. In addition, this Facility also releases its reference to an Activity Context
after the SLEE has delivered an Activity End Event to all SBB entities that are attached to the Activity
Context and can receive the Activity End Event (see Section 8.5.5). This helps the SLEE reclaim Activity
Contexts.
The reference to the Activity Context held by the Activity Context Naming Facility may prevent the Activ-
ity Context from being reclaimed, especially if the Activity object that is encapsulated by the Activity Con-
text is not ended implicitly by invoking a method, or by external events, such as disconnecting from a con-

Chapter 13
Facilities
nection. For example, if the Activity Context of a NullActivity object is referenced and the endAc-
tivity method of the NullActivity object is never invoked, then the Activity Context will never be
reclaimed.
13.5.1 ActivityContextNamingFacility interface

SBB objects access the Activity Context Naming Facility through an ActivityContextNaming-
Facility object that implements the ActivityContextNamingFacility interface. An Activ-
ityContextNamingFacility object can be found at a SLEE specification defined location in every
SBB’s component environment.
The ActivityContextNamingFacility interface is as follows:
public interface ActivityContextNamingFacility {

public void bind(ActivityContextInterface activity, String name)
NameAlreadyBoundException,
FacilityException;
public void unbind(String name)
NameNotBoundException,
FacilityException;
public ActivityContextInterface lookup(String name)
FacilityException;
}
• All methods of the ActivityContextNamingFacility interface are mandatory transac-
tional methods (see Section 9.6.1).
• The SLEE provides the concrete implementation class of an ActivityContextNaming-
Facility object. This implementation class implements the ActivityContextNaming-
Facility interface.
13.5.1.1 bind method

The bind method takes the following arguments:
• The activity argument.
This argument specifies an Activity Context Interface object that represents the Activity Context
that will be bound to a name.
• The name argument.
This argument specifies the name that will be bound to the Activity Context specified by the ac-
tivity argument. A zero-length string is not a valid argument.
The Activity Context Naming Facility references the specified Activity Context on successful completion
of this method if the Activity Context Naming Facility does not already reference the specified Activity
Context.
This method throws a java.lang.NullPointerException if the activity argument or the
name argument is null. This method throws a javax.slee.facilities.NameAlreadyBound-

Chapter 13
Facilities
Exception if the specified name is already bound (either to the same Activity Context or another Activ-
ity Co ntext). This method throws a java.lang.IllegalArgumentException if the specified
name is a zero-length string.
13.5.1.2 unbind method

The unbind method takes the following argument:
This argument specifies the name that will be unbound from the Activity Context.
The Activity Context Na ming Facility releases a reference to the Activity Context bound to the specified
name on successful completion of this method if the Activity Context is only bound to the specified name.
This method throws a java.lang.NullPointerException if the activity argument or the
name argument is null. This method throws a javax.slee.facilities.NameNotBound-
Exception if the specified name is not already bound to an Activity Context.
13.5.1.3 lookup method

The lookup method takes the following argument:
This argument specifies the name that will be used to lookup an Activity Context.
This method returns null if the name is not bound to an Activity Context. It throws a NullPointer-
Exception if the name argument is null. Otherwise, it returns a generic Activity Context Interface
object that represents the Activity Context.
13.5.2 Conference bridge example

In this example, users of the conference bridge make a call to a conference service at an 800 number. After
the caller is connected to the conference service, the caller provides a session number that specifies a con-
ference session that the caller wishes to attend.
The hypothetical Activity objects for this example are the Call objects and the ConferenceSession
objects. When a caller calls the conference service, the incoming call causes a Call object to be created
and an event to be emitted from the Call object. This event is an initial event for a new root Foo Confer-
ence SBB entity of the Foo Conference Service.
This Foo Conference SBB entity obtains the session number from the caller and uses the session number to
construct a unique name that represents the session, e.g. “com.foobar.FooConference.800:session=” + ses-
sion number. It looks up this name in the Activity Context Naming Facility.
• If this name is not already bound to an Activity Context, then the Foo Conference SBB entity in-
vokes the Conference Bridge resource to create a new conference session. The Conference Bridge
resource returns new a ConferenceSession object that represents the conference session. The
SBB entity obtains the Activity Context of the ConferenceSession object and invokes the
Activity Context Naming Facility to bind the above unique name of the conference session to the
Activity Context of the ConferenceSession object.
• If this name is already bound to an Activity Context, then the Activity Context Naming Facility re-
turns the Activity Context bound to this name. This Activity Context should encapsulate the Con-
ferenceSession object that represents the conference session specified by the session num-
ber. This conference session has been created earlier by another Foo Conference SBB entity.
In either case, the Foo Conference SBB entity connects the call to the conference session, and attaches it-
self to the Activity Context of the ConferenceSession object.

Chapter 13
Facilities
The Activity Context Naming Facility allows Foo Conference SBB entities to locate a “shared” Activity
Context that represents a conference session, and to maintain shared state relating to the conference ses-
sions, such as the total number of callers on the conference session and other similar statistics.
13.6 Profile Facility

The Profile Facility allows SBBs to search for Profiles stored in Profile Tables by attribute value.
13.6.1 ProfileFacility interface

SBB objects access the Profile Facility through a ProfileFacility object that implements the Pro-
fileFacility interface. A ProfileFacility object can be found at a SLEE specification defined
location in every SBB’s comp onent environment.
The ProfileFacility interface is as follows:
import javax.slee.TransactionRolledbackLocalException;
public interface ProfileFacility {

public Collection getProfiles(String profileTableName)
UnrecognizedProfileTableNameException,
FacilityException;
public Collection getProfilesByIndexedAttribute(String profileTableName,
String attributeName, Object attributeValue)
UnrecognizedAttributeException,
AttributeNotIndexedException,
AttributeTypeMismatchException,
FacilityException;
public ProfileID getProfileByIndexedAttribute(String profileTableName,
FacilityException;
public ProfileTableActivity
getProfileTableActivity(String profileTableName)
FacilityException;
}
• All methods of the ProfileFacility interface are required transactional methods.

• The SLEE provides the concrete implementation class of a ProfileFacility object. This im-
plementation class implements the ProfileFacility interface.
• All methods of the ProfileFacility interface are required transactional methods (see Sec-
tion 9.6.2). They throw a javax.slee.TransactionRolledbackLocalException if
they are invoked without a valid transaction context and the transaction started for the invocation
fails to commit.
if the requested operation cannot be c ompleted because of a system-level failure.

Chapter 13
Facilities
13.6.1.1 getProfiles method

The getProfiles method returns a Collection object that contains the Profile identifiers of the Pro-
files in the Profile Table identified by the profileTableName argument.
• The returned Collection object is immutable. Any attempts to modify the returned Collec-
tion object, whether direct or via its Iterator objects, result in an java.lang.Unsup-
portedOperationException.
• The default Profile of the specified Profile Table is not considered to be in the Profile Table and
will not be included in the collection since the default Profile does not have a Profile identifier.
• An Iterator object can be obtained from the Collection object that can be used to iterate
over the Profile identifiers (i.e. the next method of the Iterator object returns a ProfileID
object) of the Profiles in the Profile Table.
• If the profileTableName argument does not identify a Profile Table recognized by the SLEE,
the method throws a javax.slee.profile.UnrecognizedProfileTableName-
Exception. If the profileTableName argument is null, the method throws a
java.lang.NullPointerException.
• The Collection object, its Iterator objects, and the Profile identifiers obtained from these
objects are only valid within the transaction that returned the Collection object.
13.6.1.2 getProfilesByIndexedAttribute method

The getProfilesByIndexedAttribute method returns a Collection object that contains the
Profile identifiers of the Profiles in the Profile Table identified by the profileTableName argument
that satisfies the search criteria specified by the attributeName and attributeValue arguments.
The attributeName attribute identifies the indexed attribute searched and the attributeValue
argument identifies the value to look for in the specified attribute.
• If the Java type of the attribute specified by the attributeName argument is not an array type,
a Profile satisfies the search criteria if the value stored in the specified attribute is equal to the
value specified by the attributeValue argument. If the Java type of the indexed attribute is
not a primitive Java type, the appropriate Java type of the attributeValue argument must be
the same as the Java type of the indexed attribute. If the Java type of the indexed attribute is a
primitive Java type, the appropriate Java type of the attributeValue argument must be the
Java wrapper class for the primitive type of the indexed attribute.
• If the Java type of the attribute specified by the attributeName argument is an array type, a
Profile satisfies the search criteria if any element of the array object stored in the specified attrib-
ute is equal to the value specified by the attributeValue argument. If the Java type of the ar-
ray element is not a primitive Java type, the appropriate Java type of the attributeValue ar-
gument must be the same as the Java type of the array element. If the Java type of the array ele-
ment is a primitive Java type, the appropriate Java type of the attributeValue argument must
be the Java wrapper class for the primitive type of the array element.
• If the Java type of the attributeValue argument is not an appropriate type for the indexed at-
tribute, then this method throws a javax.slee.profile.AttributeTypeMismatch-
Exception.
• The returned Collection object is immutable. Any attempts to modify the returned Collec-
tion object, whether direct or via its Iterator objects, result in an java.lang.Unsup-
portedOperationException.
• The default Profile of the specified Profile Table is not considered to be in the Profile Table and

Chapter 13
Facilities
• An Iterator object can be obtained from the Collection object that can be used to iterate
over the Profile identifiers (i.e. the next method of the Iterator object returns a ProfileID
object) of the Profiles in the Profile Table.
• If the profileTableName argument does not identify a Profile Table recognized by the SLEE,
the method throws a javax.slee.profile.UnrecognizedProfileTableName-
Exception. If the attributeName argument does not identify an attribute of the Profile Ta-
ble, then the method throws a javax.slee.profile.UnrecognizedAttribute-
Exception. If the attributeName argument identifies an attribute that is not indexed, then
the method throws a javax.slee.profile.AttributeNotIndexedException. If any
of the method’s arguments are null, the method throws a java.lang.NullPointer-
Exception.
• The Collection object, its Iterator objects, and the Profile identifiers obtained from these
objects are only valid within the transaction that returned the Collection object.
13.6.1.3 getProfileByIndexedAttribute method

The getProfileByIndexedAttribute method has the same semantics as the getProfilesBy-
IndexedAttribute method except that the Profile identifier of the first Profile that satisfies the search
criteria is returned. (The SLEE can stop the search after the first match.) This method returns null if no
Profile in the specified Profile Table satisfies the search criteria.
13.6.1.4 getProfileTableActivity method

The getProfileTableActivity method returns the Activity object of the Profile Table specified by
the profileTableName argument. If the profileTableName argument does not identify a Profile
Table recognized by the SLEE, the method throws a javax.slee.profile.Unrecognized-
ProfileTableNameException. If the profileTableName argument is null, the method throws
a java.lang.NullPointerException.
13.7 Format of the alarm type and message type string

The alarm type and message type allow the SBB Developer to provide additional classification information
about the alarms or trace messages emitted by SBBs. The management client can use this classification
information to filter the alarm notifications and trace notifications.
The alarm type and message type have been added to these notifications because the notification types of
all notifications emitted by an MBean object should not change over the lifetime of the MBean object.
Hence, the notification type cannot be used by SBBs to store classification information that may be used to
perform additional filtering.
The SLEE strongly recommends that SBB Developers use the dot notation format of Java Properties and
follow the following naming convention:
• “slee.xxx” is reserved for future use by the SLEE specification.
• “sbb.vendorname.xxx” is recommended for SBB Developers to annotate the various alarm types
and message types that an SBB from a specific vendor can emit.
• “resourcename.vendorname.xxx” is recommended to annotate the various alarm types and mes-
sage types that a specific resource from a specific vendor can emit.
13.8 JNDI names of SLEE Facilities

The following table lists the SLEE specification defined names of the objects of SLEE Facilities under
java:comp/env.
Objects Names

Chapter 13
Facilities
TimerFacility object slee/facilities/timer

AlarmFacility object slee/facilities/alarm
TraceFacility object slee/facilities/trace
ActivityContextNamingFacility slee/facilities/activitycontextnaming
object
ProfileFacility object slee/facilities/profile
ProfileTableActivityContextInter slee/facilities/profiletableactivitycontextinterfacefactory
faceFactory object

Chapter 14
Management
Chapter 14 Management
The JAIN SLEE specification provides management capabilities for deployment units, Services, Profile
Tables, Profiles, the Alarm Facility, and the Trace Facility.
A management client manages the SLEE by interacting with a set of SLEE specification defined MBean
objects, as defined by the Java Management Extension (JMX) specification. The SLEE specification de-
fines the MBean interface of these MBean objects and the requirements for the MBean classes that imple-
ment these MBean interfaces.
14.1 Motivation for JMX instrumentation

The JMX instrumentation model was chosen for the following reasons:
• It enables the SLEE to be managed without heavy investment.
Implementing instrumentation that conforms to the JMX architecture is easy.
• It provides scaleable management architecture.
The component-based approach of JMX means that JMX solutions, including the SLEE and its
management clients, can scale from small devices to large telecommunications switches and be-
yond.
• It integrates easily with existing management solutions.
Systems instrumented using JMX can be managed through HTML browsers or by various man-
agement protocols such as SNMP, TMN and WBEM. JMX instrumentation is protocol independ-
ent.
14.2 SLEE MBean interfaces and classes

The SLEE MBean interfaces are the MBean interfaces defined by the SLEE specification. The SLEE speci-
fication defines the following MBean interfaces in the javax.slee.management package:
• The SleeManagementMBean interface.
• The DeploymentMBean interface.
• The ServiceManagementMBean interface.
• The ServiceUsageMBean interface.
• The ProfileProvisioningMBean interface.
• The AlarmMBean interface.
• The TraceMBean interface.
A SLEE MBean class is a class that implements a particular SLEE MBean interface in accordance with the
JMX specification. For example the Service Management MBean class presents the javax.slee.ma-
nagement.ServiceManagementMBean interface to the MBean Server and implements the attributes
and operations defined by this interface.
14.2.1 Implementation requirements for a SLEE MBean class

The following are the requirements that must be considered in the implementation of a SLEE MBean class.
• The SLEE MBean class must be implemented in accordance with the JMX 1.0 specification.
• The SLEE MBean class can be implemented as a standard MBean, a dynamic MBean, or a model
MBean, but must present the corresponding SLEE MBean interface to the MBean Server.
• Where a SLEE MBean interface defines a get and/or set accessor method that follows the design
pattern for a managed attribute, the SLEE MBean class must ensure that the target of the accessor

Chapter 14
Management
is accessible and/or updateable via both the invoke and getAttribute / setAttribute
methods of the MBean Server. This is the default behavior of a standard MBean. The attribute
name as passed to getAttribute / setAttribute is case sensitive, and must match the
get/set method(s). e.g. for getState , the attribute name is “State”.
• If a method defined in a SLEE MBean interface returns one or more Object Names of other SLEE
MBean objects, the implementation of the method must make sure that the respective MBean ob-
jects are registered with the SLEE’s MBean Server before returning.
• If the SLEE MBean class generates notifications, it must implement the JMX javax.manage-
ment.NotificationBroadcaster interface. The SLEE MBean interface itself does not ex-
tend this interface directly as the addNotificationListener and removeNotifi-
cationListener methods of the NotificationBroadcaster interface should not be
exposed as management operations that can be invoked by the management client. Notification lis-
teners should be added or removed via the MBean Server.
The implementation classes of the following SLEE MBean interfaces emit notifications and must
implement the NotificationBroadcaster interface:
o The SleeManagementMBean interface.
A SleeManagementMBean object generates SLEE state change notifications.
o The AlarmMBean interface.
An AlarmMBean object generates alarm notifications.
o The TraceMBean interface.
A TraceMBean object generates emits trace notifications.
o The SBB Usage MBean interface (see Section 14.10).
An SBB Usage MBean object generates usage notifications.
Each of these implementation classes must implement the notification broadcaster semantics de-
fined by the JMX specification. This includes the filtering semantics defined by the JMX No ti-
ficationBroadcaster and NotificationFilter interfaces.
14.2.2 Requirements for the management client

The following are the requirements for the management client that accesses the SLEE MBean objects.
• The management client may not hold any direct references to a SLEE MBean object. It may only
reference a SLEE MBean object by its Object Name. In other words, it can only invoke a SLEE
MBean object through an MBean Server, and it identifies the SLEE MBean object to be invoked
by the Object Name of the SLEE MBean object.
• Since the management client cannot hold a direct reference to a SLEE MBean object, it cannot di-
rectly add or remove itself as a notification listener to a SLEE MBean object that implements the
NotificationBroadcaster interface. Rather, the management client registers and removes
a listener by invoking the MBean Server’s addNotificationListener and removeNoti-
ficationListener methods, pas sing to these methods the Object Name of the SLEE MBean
object that the management client wants to begin or stop receiving notifications from.
14.3 Accessing the MBean Server and SLEE MBean objects

The SLEE specification mandates the use of the JMX MLe t (management applet) specification in order for
management clients to gain access to the SLEE MBean Server and SLEE MBean objects.
14.3.1 Requirements of the Management Client

The vendor of a SLEE management client must define and implement an MLet MBean that acts as a JMX
connector or protocol adaptor. This MLet is registered with the SLEE MBean Server and provides an ad-
Chapter 14
Management
aptation layer between the SLEE management operations and the management client’s front end. The
management client MLet can use any proprietary mechanism in order to communicate requests and re-
sponses from the front end to the SLEE’s MBean Server.
The requirements of the management client MLet MBean are:
• The MLet must be implemented in accordance with the JMX 1.0 specification for MBeans.
• The MLet can be implemented as a standard MBean, a dynamic MBean, or a model MBean.
• The MLet should implement the javax.management.MBeanRegistration interface.
The preRegister method defined in this interface provides the MLet with the MBean Server
instance that the SLEE MBean objects are registered with.
• A suitable MLet text file that provides the necessary codebase and instantiation class information
should be provided with the MLet distribution.
14.3.2 Requirements of the SLEE Vendor

The SLEE specification requires that a SLEE vendor implement the necessary functionality to load and
instantiate management client MLet MBeans using the MLet specification. The javax.management.-
loading.MLet MBean can be used by a SLEE implementation to perform the actual parsing of an MLet
text file and instantiation of the MBeans defined in it. The SLEE must ensure that the MBean Server that
the MLets are registered with is the same MBean Server (or a remote image of it) that the SLEE MBean
objects are registered with in order for the MLet to invoke the SLEE’s management operations.
The SLEE specification does not strictly define when during a SLEE’s lifetime management client MLets
should be instantiated. However, the earliest that a SLEE implementation should instantiate MLets is after
the initialization phase is complete and the SLEE is ready to accept management operations. MLets may
be instantiated any time after this point at the discretion of the SLEE implementation.
14.3.3 Accessing SLEE MBean objects

Figure 16 illustrates the access paths to the Object Names of the various MBean objects that provide the
e xternal management interface of the SLEE.

Chapter 14
Management
AlarmMBean
object
Deployment-
MBean
object
SleeProvider Service- ServiceUsage-

SleeManagement- Management-
object MBean MBean MBean
object objects
object
TraceMBean
object
Profile-
Provisioning- NamesMBean
MBean objects
object
Figure 16 Access paths to the SLEE MBean objects

The SLEE specification defines a SleeProviderFactory class. A management client MLet invokes a
static method on this factory class to obtain an object that implements the SleeProvider interface. This
SleeProvider object provides the management client MLet with the Object Name of the SleeMan-
agementMBean object. Using the MBean Server that it is registered with, the management client MLet
can:
• use the Object Name of the SleeManagementMBean object to obtain the names of other SLEE
MBean objects (as shown in Figure 16),
• invoke SLEE MBean objects,
• add and remove notification listeners to the SLEE MBean objects that generate notifications.
14.4 SleeProviderFactory class

The SleeProviderFactory class provides static methods for obtaining an object instance of a SLEE
vendor implemented concrete class that implements the SleeProvider interface. The SleeProvid-
erFactory class is as follows:
package javax.slee.management;
public final class SleeProviderFactory {

public static SleeProvider getSleeProvider(String peerClassName)
PeerUnavailableException { … }
public static SleeProvider getSleeProvider( String peerClassName,
ClassLoader classloader)
PeerUnavailableException { … }
}

Chapter 14
Management
14.4.1 getSleeProvider methods

The getSleeProvider methods take the following argument:
• The peerClassName argument.
This argument specifies the fully qualified class name of the concrete SLEE vendor impleme nted
Java class that implements the SleeProvider interface.
The second form of the getSleeProvider method also takes the following argument:
• The classloader argument.
This argument specifies a class loader that should be used to load the class specified by the
peerClassName argument.
These methods attempt to instantiate an object instance of the specified Java class, and, if successful, return
the instantiated SleeProvider object.
These methods throw a java.lang.NullPointerException if peerClassName is null. In the
second form, a NullPointerException is also thrown if classloader is null. It throws a
javax.slee.management.PeerUnavailableException if the peerClassName argument
does not identify a class that implements the SleeProvider interface (in some cases the specified class
cannot be found, or the argument is not well-formed).
14.5 Vendor implemented SleeProvider concrete class

A SLEE vendor must provide at least one concrete class that implements the SleeProvider interface.
The vendor implementation allows a management client MLet to obtain the Object Name of the Slee-
ManagementMBean, which allows a management client to manage the SLEE.
Typically, a management client obtains an instance of this concrete class via the getSleeProvider
method of the SleeProviderFactory. This concrete class must define a public no-argument construc-
tor for use by the getSleeProvider method.
The SleeProvider interface is as follows:
import javax.management.ObjectName;
public interface SleeProvider {

public ObjectName getSleeManagementMBean();
}
• The getSleeManagementMBean method.
It returns the Object Name of a SleeManagementMBean object.
14.6 SleeManagementMBean interface

The SleeManagementMBean interface defines the main management interface of the SLEE. It can be
used to:
• Change the operational state of the SLEE.
• Obtain the JMX Object Names of the AlarmMBean, DeploymentMBean, ServiceManage-
mentMBean, TraceMBean, and ProfileProvisioningMBean ob jects.
The management client obtains the Object Name of a SleeManagementMBean object by invoking the
getSleeManagementMBean method on a SleeProvider object.
Each time the operational state of the SLEE changes, the SleeManagementMBean object generates a
SLEE state change notification. The SleeStateChangeNotification class defines the information
encapsulated in each SLEE state change notification. The concrete class that implements the Slee-

Chapter 14
Management
ManagementMBean interface must extend the NotificationBroadcaster interface even though

the SleeManagementMBean interface does not extend the NotificationBroadcaster interface
14.6.1 Operational states of the SLEE

The following figure illustrates the operational states of the SLEE and permitted transitions between these
states.
Starting
start( ) *
Stopped * Running
shutdown()
stop( )
*
Stopping
Figure 17 Operational states of the SLEE

(an asterisk * denotes a spontaneous transition)
• Stopped state.
The SLEE environment is configured and initialized, ready to be started. This means “active” re-
source adaptor entities are loaded and initialized, and SBBs corresponding to “Active” Services
are loaded and ready to be instantiated. However the entire event-driven subsystem is idle. Re-
source adaptor entities and the SLEE are not actively producing events, and the event router is not
operating. SBB entities are not created in this state.
o Transitions:
Stopped to Starting: The SLEE has no operations to execute
Stopped to Does Not Exist: The SLEE process(es) shutdown and terminate gracefully.
• Starting state.
“Active” resource adaptor entities are activated. Any other vendor-specific starting state tasks
may be performed here. SBB entities are still not created in this state. The SLEE spontaneously
moves out of this state when (a) startup tasks are complete, which causes transition to the Running
state; (b) some startup task fails , which causes transition to the Stopping state.
o Transitions:
Starting to Running: The event router is started. ServiceActivity objects are cre-

Chapter 14
Management
ated for Services whose persistent state say they should be active, and a Service Started
Event is are fired on each of these ServiceActivity objects .
Starting to Stopping: The SLEE has no operations to execute.
• Running state.
“Active” resource adaptor entities (and the SLEE) are actively firing events as conditions dictate.
The event router is instantiating SBB entities and delivering events to them as required.
o Transitions:
Running to Stopping: Any ServiceActivity objects or ProfileTableActiv-
ity objects that exist are ended by the SLEE, and an Activity End Event is fired on each
of them.
• Stopping state.
This state is identical to the Running state except no new Activity objects are accepted from re-
source adaptor entities or created by the SLEE. Existing Activity objects are allowed to end (sub-
ject to an arbitrary vendor-specified timeout). The SLEE spontaneously moves out of this state
when all Activity objects have ended. If this state is reached from the Starting state, there will be
no existing Activity objects and transition to the Stopped state should immediately occur.
o Transitions:
Stopping to Stopped: Any resource adaptor entities that were active are deactivated so
they do not produce any further events. If the event router had been started, it is stopped.
The implementation of a SLEE must ensure that shutdown cannot fail. For example, if a
resource adaptor entity fails to deactivate properly, the SLEE should just ignore any fur-
ther events it produces.
The Stopped and Running states are stable, in that spontaneous transitions to other states do not occur. The
Starting and Stopping states are transitional hence spontaneously move to another state as conditions dic-
tate.
14.6.1.1 Initialization and initial state

When a SLEE boots, it may exist in an indeterminate state until it is fully initialized. After initialization has
completed, the SLEE enters the Stopped state. Management connections must only be permitted once the
SLEE enters a valid state, therefore while the SLEE is initializing client connections must be rejected. The
simplest way to achieve this is to delay the instantiation of management client MLets until the very end of
the initialization cycle.
A SLEE vendor may choose to persist the operational state of the SLEE and re -enter that state when the
SLEE server process(es) restart. For example, if a SLEE was in the Running state when it e xperienced a
critical failure, on restart the SLEE may automatically attempt to re-enter the Running state and continue.
In doing so however, the SLEE must migrate through the Stopped and Starting states as normal before re -
entering the Running state (or Stopping state, if the restart fails).
14.6.1.2 Management operations and SLEE state

The SLEE state has no effect on the availability of any management MBean. A SLEE vendor may pre-
scribe when management operations may be available, however they may only do so by limiting the avail-
ability of a SLEE MBean Server. If a SLEE instantiates and registers a management client MLet with an
MBean Server, the SLEE vendor must ensure that the SLEE allows full and total access to its management
subsystem via that MBean Server.
A SLEE vendor is free to make more than one SLEE MBean Server available for management clients to
execute management operations. Where more than one SLEE MBean Server is available at a single point in
time, it is the responsibility of the SLEE vendor to maintain a consistent management image across the
multiple MBean Servers.

Chapter 14
Management
14.6.2 SleeManagementMBean interface

The SleeManagementMBean interface is as follows:
public interface SleeManagementMBean {

// JMX notification type of SLEE State Change notification
public static final String SLEE_STATE_CHANGE_NOTIFICATION_TYPE =
"javax.slee.management.sleestatechange";
// get current operational state of the SLEE

public SleeState getState()
throws ManagementException;
// change operational state of the SLEE

public void start() throws InvalidStateException, ManagementException;
public void stop() throws InvalidStateException, ManagementException;
public void shutdown() throws InvalidStateException, ManagementException;
// get the Object Names of the other SLEE MBean objects made accessible
// by this SleeManagementMBean object
public ObjectName getDeploymentMBean();
public ObjectName getServiceManagementMBean();
public ObjectName getProfileProvisioningMBean();
public ObjectName getTraceMBean();
public ObjectName getAlarmMBean();
}
• The getState method.
This method returns a SleeState object that indicates the current operational state of the SLEE.
o It throws a javax.slee.management.Management Exception if the current
operational state of the SLEE cannot be obtained due to a system-level failure.
• Methods that change the operational state of the SLEE, i.e. start and stop.
o The start method.
This method can only be called when the SLEE is in the Stopped state, and causes propa-
gation to the Starting state
§ Conditions:
Pre: SleeManagementMBean.getState() == SleeState.STOPPED
Post: SleeManagementMBean.getState() == SleeState.START-
ING
o The stop method.
This method can only be called when the SLEE is in the Running state, and causes
propagation to the Stopping state.
§ Conditions:
Pre: SleeManagementMBean.getState() == SleeState. RUNNING
Post: SleeManagementMBean.getState() == SleeState.STOP-
PING
o The shutdown method.
This method can only be called when the SLEE is in the Stopped state, and causes all
SLEE processes running under the same server image to shutdown and terminate in a
graceful manner.
§ Conditions:
Pre: SleeManagementMBean.getState() == SleeState.STOPPED
Post: SLEE server processes no longer exist for the respective server image.

Chapter 14
Management
The start and stop methods should not block. The operations the SLEE needs to perform in
the transitional states, and further transitions to stable states, should be performed in a separate
thread of execution to the thread that invoked the start or stop management operation.
The shutdown method should never return, i.e. System.exit() should be invoked before
control is returned to the caller.
o The above methods may throw the following exceptions:
§ javax.slee.InvalidStateException.
This exception is thrown if a requested change to the operational state of the
SLEE is not permitted from the current operational state.
§ javax.slee.management.ManagementException.
If the requested operation cannot be performed due to a system-level failure,
then the method throws a ManagementException. The requested operation
may be valid but the SLEE cannot perform the requested operation due to a sys-
tem-level failure, or the SLEE cannot determine whether the requested operation
is valid due to a system-level failure.
• Methods that get the Object Names of the SLEE MBean objects made accessible by this Slee-
ManagementMBean object.
o The getDeploymentMBean method
o The getServiceManagementMBean method
o The getProfileProvisioningMBean method.
o The getTraceMBean method
o The getAlarmMBean method
The implementation of these methods must make sure that the requested MBean Object Name is
registered with the SLEE MBean Server before returning.
14.6.3 SleeState objects

The SleeState class defines an enumerated type for the operational states of the SLEE. A singleton in-
stance of each enumerated value is guaranteed (via an implementation of the readResolve method, see
java.io.Serializable for more details), so that equality tests using == are always evaluated cor-
rectly. For convenience, an integer representation of SleeState objects is also available.
The following singleton objects define the valid argument or return values for SleeState objects.
• STOPPED
• STARTING
• RUNNING
• STOPPING
The public contents of the SleeState class is as follows:
public final class SleeState implements java.io.Serializable {

// singletons
public static final SleeState STOPPED …;
public static final SleeState STARTING …;
public static final SleeState RUNNING …;
public static final SleeState STOPPING …;
public static final int SLEE_STOPPED …;

Chapter 14
Management
public static final int SLEE_STARTING …;

public static final int SLEE_RUNNING …;
public static final int SLEE_STOPPING …;
// methods
public boolean isStopped() { … }
public boolean isStarting(){ … }
public boolean isRunning() { … }
public boolean isStopping() { … }
public static SleeState fromInt(int state)

public int hashCode(){ … }
public String toString(){ … }
}
• Each of the is<State> methods determines if this SleeState object represents the
<State> operational state, and is equivalent to (this == <STATE>). For example, the
isStopped method determines if this SleeState object represents the Stopped operational
state and is equivalent to (this == STOPPED).
• The fromInt and toInt methods allow conversion between the SleeState object form and
numeric form.
• The fromInt method throws a java.lang.IllegalArgumentException if the state
argument is not one of the four integer state representations.
14.6.4 SleeStateChangeNotification class

The public interface of the SleeStateChangeNotification class is as follows:
import javax.management.Notification;
public class SleeStateChangeNotification extends Notification {

public SleeStateChangeNotification(SleeManagementMBean source,
SleeState newState,
SleeState oldState,
long sequenceNumber) { … }
public final SleeState getNewState() { … }
public final SleeState getOldState() { … }
}
14.7 DeploymentMBean interface

The DeploymentMBean interface defines the management API for installing and remo v ing components
into and out of the SLEE and for interrogating these components.
The Object Name of a DeploymentMBean object may be obtained using the getDeploymentMBean
method on a SleeProviderMBean object.
14.7.1 Components that can be installed

Installable components must be packaged into a deployable unit jar file before they can be installed into the
SLEE. A deployable unit jar file may contain any number or combination of the following components:
• SBB jar file.
An SBB jar file contains the class files and deployment descriptors for one or more SBBs (see
Section 3.1.9).

Chapter 14
Management
• Event jar file.

An event jar file contains the class files and deployment descriptors for one or more event types
• Profile Specification jar file.
A Profile Specification jar file contains the class files and deployment descriptors for one or more
Profile Specifications (see Section 3.3.6).
• Resource adaptor type jar file.
A resource adaptor type jar file contains the class files and deployment descriptors for one or more
resource adaptor types (see Section 15.1.4).
• Resource adaptor file.
A resource adaptor jar file contains the class files and deployment descriptors for one or more re -
source adaptors (see Section 15.2.3).
• Service XML file.
A Service XML file is a deployment descriptor file that contains the definition of one or more Ser-
vices (see Section 3.4.1).
A deployable unit jar file may also contain other vendor-specific components.
The deployment descriptor for a deployable unit jar file is described in Section 3.4.5.
14.7.2 Pre-conditions for installing and uninstalling a jar file

A deployable unit cannot be installed successfully in the SLEE under the following conditions:
• The deployable unit contains a component with the same component identity as a component of
the same type that is already installed in the SLEE.
• The deployable unit contains a component that references other components that are not already
installed in the SLEE and are not included in the deployable unit jar. If a component has unre-
solved dependencies, it cannot be installed. For example, an SBB component may reference event
type components and Profile Specification components. If any of the referenced components are
not installed or included in the deployable unit jar, then the SBB component has unresolved de-
pendencies and the deployable unit cannot be installed.
• The deployable unit contains components that contain classes, interfaces or deployment descrip-
tors which do not satisfy the requirements and restrictions detailed in this specification.
A deployable unit cannot be uninstalled from the SLEE if there are any dependencies on it from comp o-
nents in other installed deployable units. For example, if a deployable unit contains an SBB jar that d epends
on a Profile Specification jar contained in a second deployable unit, the deployable unit containing the Pro-
file Specification jar cannot be uninstalled while the deployable unit containing the SBB jar remains in-
stalled.
14.7.3 Deployable unit identifiers and descriptors

When a deployable unit is installed, the SLEE assigns a unique identity to it and returns a deployable unit
identifier that encapsulates that identity. The management client uses the deployable unit identifier to query
the contents of the deployable unit and eventually uninstall the deployable unit.
The SLEE also creates a deployable unit descriptor for each installed deployable unit. This descriptor en-
capsulates the relevant deployment information specific to the deployable unit, such as the list of comp o-
nent jars contained within it.

Chapter 14
Management
14.7.3.1 DeployableUnitID interface

The DeployableUnitID interface is a marker interface implemented by every Java object that encapsu-
lates a deployable unit identity. A DeployableUnitID object is also known as a deployable unit identi-
fier.
The DeployableUnitID interface is as follows:
public interface DeployableUnitID {

}
The concrete implementation class of a deployable unit identifier should provide an appropriate implemen-
tation of the equals, hashCode, and toString methods.
this deployable unit identifier. The specified object is equal to this deployable unit identifier if the
specified object is a deployable unit identifier and it identifies the same deployable unit.
The implementation of this method should provide a reasonable hash code value for the deploy-
able unit identifier.
• The toString method.
The implementation of this method should provide a reasonable string representation for the de-
ployable unit identifier.
14.7.3.2 DeployableUnitDescriptor interface

The DeployableUnitDescriptor interface defines the interface of a Java object that describes an
installed deployable unit.
The DeployableUnitDescriptor interface is as follows:
public interface DeployableUnitDescriptor {

public String getURL();
public java.util.Date getDeploymentDate();
public ComponentID[] getComponents();
}
• The getURL method.

This method returns the URL that the deployable unit was installed from.
• The getDeploymentDate method.
This method returns the date that the deployable unit was installed.
• The getComponents method.
This method returns an array of ComponentID objects, one for each component within the de-
ployable unit.
14.7.4 Component identity

Each component that is installed into the SLEE is assigned a unique identity. The SLEE establishes com-
ponent identity from information contained in the component’s deployment descriptor. Component identity

Chapter 14
Management
is immutable while the component is installed in the SLEE. Two components of the same type that have the
same component identity cannot be installed simultaneously in the SLEE.
• SBB component identity.
An SBB’s name, vendor, and version determine the SBB’s component identity.
• Event type component identity.
An event type’s name, vendor, and version determine the event type’s component identity.
• Profile Specification component identity.
A Profile Specification’s name, vendor, and version determine the Profile Specification’s comp o-
nent identity.
• Service component identity.
A Service’s name, vendor, and version determine the Service’s component identity.
• Resource adaptor type component identity.
A resource adaptor type’s name, vendor, and version determine the resource adaptor type’s com-
ponent identity.
• Resource adaptor component identity.
A resource adaptor’s name, vendor, and version determine the resource adaptor’s component iden-
tity.
14.7.5 Component identifiers

A component identifier is a Java object that encapsulates a component’s identity. The SLEE specification
defines the following component identifier interfaces.
• The ComponentID interface is the common base interface of all comp onent identifier interfaces.
• The SbbID interface for component identifiers that encapsulate SBB component identities.
• The EventTypeID interface for component identifiers that encapsulate event type component
identities.
• The ProfileSpecificationID interface for component identifiers that encapsulate Profile
Specification component identities.
• The ServiceID interface for component identifiers that encapsulate Service component identi-
ties.
• The ResourceAdaptorTypeID interface for component identifiers that encapsulate resource
adaptor type component identities.
• The ResourceAdaptorID interface for component identifiers that encapsulate resource adap-
tor component identities.
14.7.5.1 ComponentID interface

The ComponentID interface is a marker interface used as the common base interface for all component
identifier interfaces. All Java objects that implement the ComponentID interface are also known as com-
ponent identifiers.
The ComponentID interface is as follows:
package javax.slee;
public interface ComponentID {

}

Chapter 14
Management
The concrete implementation class of a component identifier should provide an appropriate implementation
of the equals, hashCode, and toString methods.
this component identifier. The specified object is equal to this component identifier if the specified
object is a component identifier and has the same type and identity.
The implementation of this method should provide a reasonable hash code value for the comp o-
nent identifier.
• The toString method.
The implementation of this method should provide a reasonable string representation for the com-
ponent identifier.
14.7.5.2 SbbID interface

The SbbID interface is a marker interface implemented by every Java object that encapsulates an SBB’s
comp onent identity. An SbbID object is also known as an SBB identifier.
The SbbID interface is as fo llows:
package javax.slee;
public interface SbbID extends ComponentID {

}
14.7.5.3 EventTypeID interface

The EventTypeID interface is a marker interface implemented by every Java object that encapsulates an
event type’s component identity. An EventTypeID object is also known as an event type identifier.
The EventTypeID interface is as follows:
package javax.slee;
public interface EventTypeID extends ComponentID {

}
14.7.5.4 ProfileSpecificationID interface

The ProfileSpecificationID interface is a marker interface implemented by every Java object that
encapsulates a Profile Specification’s component identity. A ProfileSpecificationID object is also
known as a Profile Specification identifier.
The ProfileSpecificationID interface is as follows:
public interface ProfileSpecificationID extends ComponentID {

}
14.7.5.5 ServiceID interface

The ServiceID interface is a marker interface implemented by every Java object that encapsulates a Ser-
vice’s component identity. A ServiceID object is also known as a Service identifier.
The ServiceID interface is as follows:
package javax.slee;
public interface ServiceID extends ComponentID {

Chapter 14
Management
14.7.5.6 ResourceAdaptorTypeID interface

The ResourceAdaptorTypeID interface is a marker interface implemented by every Java object that
encapsulates a resource adaptor type’s (see Section 15.1) component identity. A ResourceAdaptor-
TypeID object is also known as a resource adaptor type identifier.
The ResourceAdaptorTypeID interface is as follows:
package javax.slee.resource;
public interface ResourceAdaptorTypeID extends ComponentID {

}
14.7.5.7 ResourceAdaptorID interface

The ResourceAdaptorID interface is a marker interface implemented by every Java object that encap-
sulates a resource adaptor’s (see Section 15.2) component identity. A ResourceAdaptorID object is
also known as a resource adaptor identifier.
The ResourceAdaptorID interface is as follows:
public interface ResourceAdaptorID extends ComponentID {

}
14.7.6 Common characteristics of component identifier interfaces

The following are the common characteristics for the deployable unit and component identifier interfaces:
• The concrete implementation class of a component identifier interface may contain additional in-
formation that helps the SLEE locate the identified jar file or component. For example, this infor-
mation may include a database key.
• A component identifier object is immutable. The values returned from the methods in a comp o-
nent identifier object do not change over the installed lifetime of the identified o bject.
14.7.7 Component descriptors

For each installed component, the SLEE also creates a component descriptor. A component descriptor en-
capsulates the relevant deployment information specific to the installed component.
• A management client that has a component identifier for an installed component can obtain a cor-
responding component descriptor by querying a DeploymentMBean object.
14.7.7.1 ComponentDescriptor interface

The ComponentDescriptor interface defines the common operations that are relevant to all comp o-
nent descriptors. All specific component descriptor interfaces extend from this common base interface.
The ComponentDescriptor interface is follows:
public interface ComponentDescriptor {

public ComponentID getID();
public String getSource();
public DeployableUnitID getDeployableUnit();
public String getName();

Chapter 14
Management
public String getVendor();

public String getVersion();
}
• The getID method.

This method returns the component identifier object for the component being described by the
component descriptor.
• The getSource method.
This method returns the name of the component jar file from which the component was installed,
or in the case of Service components, the name of the Service XML file from which the Service
was installed. This name is identical to the name provided in the relevant deployment descriptor
element in the deployable unit jar file from where the component was installed.
• The getDeployableUnit method.
This method returns the deployable unit identifier that identifies the deployable unit this comp o-
nent came from.
• The getName method.
This method returns the name of the component.
• The getVendor method.
This method returns the vendor of the component.
• The getVersion method.
This method returns the version of the component.
14.7.7.2 SbbDescriptor interface

The SbbDescriptor interface defines the attributes that describe an SBB that is installed in the SLEE.
The SbbDescriptor interface is as fo llows:
import javax.slee.EventTypeID;
import javax.slee.SbbID;
import javax.slee.profile.ProfileSpecificationID;
import javax.slee.resource.ResourceAdaptorID;
import javax.slee.resource.ResourceAdaptorTypeID;
public interface SbbDescriptor extends ComponentDescriptor {

public SbbID[] getSbbs();
public EventTypeID[] getEventTypes();
public ProfileSpecificationID[] getProfileSpecifications();
public ProfileSpecificationID getAddressProfileSpecification();
public ResourceAdaptorTypeID[] getResourceAdaptorTypes();
public String[] getResourceAdaptorEntityLinks();
}
• The getSbbs method.
This method returns an array of SbbID objects identifying the referenced SBBs used by the d e-
scribed SBB (through the sbb-ref elements in the SBB’s deployment descriptor).
• The getEventTypes method.
This method returns an array of EventTypeID objects identifying the event types used by the
described SBB (through the event elements in the SBB’s deployment descriptor).
• The getProfileSpecifications method.
This method returns an array of ProfileSpecificationID objects identifying the Profile
Specifications used by the described SBB (through the profile-spec-ref elements in the
SBB’s deployment descriptor).

Chapter 14
Management
• The getAddressProfileSpecification method.

This method returns a ProfileSpecificationID object that identifies the Address Profile
Specification of the described SBB (through the address-profile-spec-alias-ref
element in the SBB’s deployment descriptor).
• The getResourceAdaptorTypes method.
This method returns an array of ResourceAdaptorTypeID objects identifying the resource
adaptor types referenced by the described SBB (through the resource-adaptor-type-
binding elements in the SBB’s deployment descriptor).
• The getResourceAdaptorEntityLinks method.
This method returns an array of String objects which name the resource adaptor entity links ref-
erenced by the described SBB (through the resource-adaptor-entity-link elements in
the SBB’s deployment descriptor).
14.7.7.3 EventTypeDescriptor interface

The EventTypeDescriptor defines the attributes that describe an event type that is installed in the
SLEE.
The EventTypeDescriptor interface is as follows:
public interface EventTypeDescriptor extends ComponentDescriptor {

public String getEventClassName();
}
14.7.7.4 ProfileSpecificationDescriptor interface

The ProfileSpecificationDescriptor interface defines the attributes that describe a Profile
Specification that is installed in the SLEE.
The ProfileSpecificationDescriptor interface is as follows:
public interface ProfileSpecificationDescriptor extends ComponentDescriptor {

public String getCMPInterfaceName();
}
• The getCMPInterfaceName method.
This method returns the name of the Profile CMP interface of the Profile Specification.
14.7.7.5 ServiceDescriptor interface

The ServiceDescriptor interface defines the attributes that describe a Service that is installed in the
SLEE.
The ServiceDescriptor interface is as follows:
public interface ServiceDescriptor extends ComponentDescriptor {

public SbbID getRootSbb();
public String getAddressProfileTable();
public String getResourceInfoProfileTable();
}
• The getRootSbb method.
This method returns an SBB identifier object that identifies the root SBB component of the Ser-
vice.

Chapter 14
Management
• The getAddressProfileTable method.

This method returns the name of the Address Profile Table of the Service. If the Service does not
have an Address Profile Table, this method returns null.
• The getResourceInfoProfileTable method.
This method returns the name of the Resource Info Profile Table of the Service. If the Service
does not have a Resource Info Profile Table, this method returns null.
14.7.7.6 ResourceAdaptorTypeDescriptor interface

The ResourceAdaptorTypeDescriptor interface defines the attributes that describe a resource
adaptor type that is installed in the SLEE.
The ResourceAdaptorTypeDescriptor interface is as follows:
public interface ResourceAdaptorTypeDescriptor extends ComponentDescriptor {

public EventTypeID[] getEventTypes();
}
This method returns an array of EventTypeID objects identifying the event types used by the
described resource adaptor type.
14.7.7.7 ResourceAdaptorDescriptor interface

The ResourceAdaptorDescriptor interface defines the attributes that describe a resource adaptor
that is installed in the SLEE.
The ResourceAdaptorDescriptor interface is as follows:
public interface ResourceAdaptorDescriptor extends ComponentDescriptor {

public ResourceAdaptorTypeID getResourceAdaptorType();
}
• The getResourceAdaptorType method.

This method returns a resource adaptor type identifier that identifies the resource adaptor type of
the resource adaptor.
14.7.8 DeploymentMBean interface

The DeploymentMBean interface is as follows:
import java.net.MalformedURLException
import javax.slee.EventTypeID;
import javax.slee.ServiceID;
import javax.slee.resource.ResourceAdaptorID;
import javax.slee.resource.ResourceAdaptorTypeID;
public interface DeploymentMBean {

public DeployableUnitID install(String url)
MalformedURLException,
AlreadyDeployedException,
DeploymentException,

Chapter 14
Management
ManagementException;
public void uninstall(DeployableUnitID id)
UnrecognizedDeployableUnitException,
DependencyException,
InvalidStateException,
public DeployableUnitID getDeployableUnit(String url)
public DeployableUnitID[] getDeployableUnits()
public SbbID[] getSbbs()
public EventTypeID[] getEventTypes()
public ProfileSpecificationID[] getProfileSpecifications()
public ServiceID[] getServices()
public ResourceAdaptorTypeID[] getResourceAdaptorTypes()
public ResourceAdaptorID[] getResourceAdaptors()
public ComponentID[] getReferringComponents(ComponentID id)
public DeployableUnitDescriptor getDescriptor(DeployableUnitID id)
public DeployableUnitDescriptor[] getDescriptors(DeployableID[] ids)
public boolean isInstalled(DeployableUnitID id)
public ComponentDescriptor getDescriptor(ComponentID id)
public ComponentDescriptor[] getDescriptors(ComponentID[] ids)
public boolean isInstalled(ComponentID id)
}
• The install method.
This method installs the deployable unit jar file identified by the url argument. Each component
jar file contained in the deployable unit is installed by the SLEE. If all these components install
successfully, the SLEE then installs any Services contained in the deployable unit jar file. The de-
ployable unit is only successfully installed if all its included component jars and Services install
successfully. If an installation attempt fails, any components in the deployable unit that were suc-
cessfully installed must be uninstalled again before the install method returns.
A component cannot be installed if it has the same identity as a component of the same type al-
ready installed in the SLEE. Additionally, the SLEE must make other considerations depending on
the type of the component being installed.
o An SBB jar file.
An SBB contained in an SBB jar file may have references to other SBBs, event types,

Chapter 14
Management
Profile Specifications, resource adaptor types. These other components must be installed
before the SBB jar file can be successfully installed.
o An event jar file.
An event jar file contains one or more event types. An event jar file cannot be installed
successfully if one or more of the event types defined in the event jar file have the same
identity as an event already known to the SLEE, regardless who defined the existing
event type or the new event type. An SBB developer, a resource, a resource adaptor type,
a SLEE vendor, or the SLEE specification may have defined the existing event type.
o A Profile Specification jar file.
No special considerations need to be made by the SLEE when installing a Profile Specifi-
cation jar file.
o A Service XML file.
A Service described in a Service XML file can only be installed if its root SBB is already
installed.
o A resource adaptor type jar file.
A resource adaptor type jar file contains one or more resource adaptor types. A resource
adaptor type may have references to event types. These event types must be installed be-
fore the resource adaptor type jar file can be successfully installed.
o A resource adaptor file.
A resource adaptor jar file can only be installed if the resource adaptor types referenced
by the resource adaptors in t he resource adaptor jar file are already installed.
The install method may throw the following exceptions.
o MalformedURLException.
This exception is thrown if the url parameter is not a properly formatted URL.
o javax.slee.management.AlreadyDeployedException.
If the deployable unit contains a component with the same component identity as a com-
ponent of the same type that is already installed in the SLEE, an AlreadyDe-
ployedException exception is thrown.
o javax.slee.management.DeploymentException.
This exception is thrown if a component could not be installed due to a problem directly
related to it or its contents. For example a contained component may fail a SLEE compli-
ance check, a referenced component may not be installed, or a required class file might
be missing from the jar.
• The uninstall method.
This method uninstalls the deployable unit specified by the id argument. Uninstalling a deploy-
able unit causes all the components in the deployable unit to be uninstalled. A deployable unit
cannot be uninstalled if any component contained in any other deployable unit depends on a com-
ponent contained in the deployable unit being uninstalled.
o An SBB jar file cannot be uninstalled while the SBB defined in the SBB jar file is refe r-
enced by other SBBs or Services installed in the SLEE. The getReferringCompon-
ents method may be used to determine the set of SBBs and Services that reference an
SBB.
o An event jar file cannot be uninstalled while any of the event types defined in the event
jar file are referenced by SBBs or resource adaptor types installed in the SLEE. The
getReferringComponents method may be used to determine the set of SBBs and
resource adaptor types that reference an event type.

Chapter 14
Management
o A Profile Specification jar file cannot be uninstalled while SBBs that depend on it are in-
stalled. The getReferringComponents method may be used to determine the set of
SBBs that reference a Profile Specification.
o No special considerations need to be made by the SLEE when uninstalling a Service
XML file.
o A resource adaptor type jar file cannot be uninstalled while SBBs or resource adaptors
that depend on it are installed. The getReferringComponents method may be used
to determine the set of SBBs and resource adaptors that reference a resource adaptor type.
o A resource adaptor jar file cannot be uninstalled while SBBs that depend on it are in-
stalled. The getReferringComponents method may be used to determine the set of
SBBs that reference a resource.
This method may throw the following exceptions.
o javax.slee.management.UnrecognizedDeployableUnitException.
This exception is thrown if the deployable unit identifier passed in as an argument is not
recognized by the SLEE as a valid identifier.
o javax.slee.management.DependencyException.
This exception is thrown if one or more of the components included in the deployable
unit are being referenced by a component in another installed deployable unit.
o javax.slee.InvalidStateException.
This exception is thrown if one or more of the components included in the deployable
unit cannot be uninstalled because the component is in a state that does not allow the
component to be uninstalled. For example, a Service cannot be uninstalled while it is in
the “ACTIVE” state.
• The getDeployableUnit method.
This method returns a DeployableUnitID object when provided with the URL of a deploy-
able unit installed in the SLEE.
This method may throw the following exception.
o javax.slee.management.UnrecognizedDeployableUnitException.
This exception is thrown if the URL passed as an argument does not correspond to a de-
ployable unit installed in the SLEE.
• The getDeployableUnits method.
This method returns an array of DeployableUnitID objects containing the identifiers of all
the deployable units installed in the SLEE.
• The getSbbs method.
This method returns an array of SbbID objects containing the identifiers of all the SBBs installed
in the SLEE.
This method returns an array of EventTypeID objects containing the identifiers of all the event
types installed in the SLEE.
• The getProfileSpecifications method.
This method returns an array of ProfileSpecificationID objects containing the identifiers
of all the Profile Specifications installed in the SLEE.
• The getServices method.
This method returns an array of ServiceID objects containing the identifiers of all the Services
installed in the SLEE.

Chapter 14
Management
• The getResourceAdaptorTypes method.

This method returns an array of ResourceAdaptorTypeID objects containing the identifiers
of all the resource adaptor types installed in the SLEE.
• The getResourceAdaptors method.
This method returns an array of ResourceAdaptorID objects containing the identifiers of all
the resource adaptors installed in the SLEE.
• The getReferringComponents method.
This method returns an array of ComponentID objects that identify the components that use or
make reference to the component specified by the id argument. This method can be used to de-
termine if there are any other installed components depending on the specified component.
This method may throw the following exception:
o javax.slee.UnrecognizedComponentException.
This exception is thrown if the component identifier passed in as an argument is not rec-
ognized by the SLEE as a valid identifier.
• The getDescriptor(DeployableUnit id) method.
This method returns a deployable unit descriptor object for the deployable unit identifier specified
by the id argument.
o javax.slee.UnrecognizedDeployableUnitException.
This exception is thrown if the deployable unit identifier passed in as an argument is not
recognized by the SLEE as a valid identifier.
• The getDescriptors(DeployableUnit ids[]) method.
This method performs the function of the above getDescriptor method over an array of de -
ployable unit identifiers. The returned array has the same length as the array passed in by the ids
argument, and if descriptors = getDescriptors(ids), then descriptors[i] ==
getDescriptor(ids[i]). If the ids array contains any deployable unit identifier that is un-
recognized by the SLEE, the returned array contains a null value at the corresponding array in-
dex position.
• The isInstalled(DeployableUnitID id) method.
This method determines if the deployable unit identified by the id argument is currently installed
in the SLEE. It returns true if the deployable unit is currently installed in the SLEE, otherwise, it
returns false.
• The getDescriptor(DeployableUnit id) method.
This method returns a component descriptor object for the component identifier specified by the
id argument. The actual type of the descriptor object returned will corres pond to the type of the
identifier provided. For example, if a ServiceID identifier is given as an argument, a Ser-
viceDescriptor object will be returned.
• The getDescriptors(ComponentID ids[]) method.
This method performs the function of the above getDescriptor method over an array of com-
ponent identifiers. The returned array has the same length as the array passed in by the ids argu-
ment, and if descriptors = getDescriptors(ids), then descriptors[i] ==
getDescriptor(ids[i]). If the ids array contains any component identifier that is unrec-

Chapter 14
Management
ognized by the SLEE, the returned array contains a null value at the corresponding array index
position.
• The isInstalled(ComponentID id) method.
This method determines if the component identified by the id argument is currently installed in
the SLEE. It returns true if the component is currently installed in the SLEE, otherwise, it re-
turns false.
• The above methods may also throw the following exceptions:
o javax.slee.management.ManagementException.
If the requested operation cannot be performed due to a system-level failure, then the
method throws a ManagementException. The requested operation may be valid but
the SLEE cannot perform the requested operation due to a system-level failure, or the
SLEE cannot determine whether the requested operation is valid due to a system-level
failure.
o java.lang.NullPointerException.
If any of a method’s arguments are null, the method throws a NullPointer-
Exception.
14.8 ServiceManagementMBean interface

The ServiceManagementMBean interface defines the management API for Services installed in the
SLEE. It can be used to:
• Change the operational state of a Service (see Section 2.2.17).
• Obtain the JMX Object Names of ServiceUsageMBean objects.
The ServiceManagementMBean interface is as follows:
import javax.slee.UnrecognizedServiceException;
public interface ServiceManagementMBean {

public ServiceState getState(ServiceID id)
UnrecognizedServiceException,
public ServiceID[] getServices(ServiceState state)
public void activate(ServiceID id)
public void activate(ServiceID ids[])
InvalidArgumentException,
public void deactivate(ServiceID id)
public void deactivate(ServiceID ids[])

Chapter 14
Management
public void deactivateAndActivate(ServiceID deactivateId,
ServiceID activateId)
public void deactivateAndActivate(ServiceID deactivateIds[],
ServiceID activateIds[])
public ObjectName getServiceUsageMBean(ServiceID id)
}
• The getState method.
This method returns the current operational state of the Service specified by the id argument.
• The getServices method.
This method returns an array of ServiceID objects that represent Services that are in the opera-
tional state specified by the state argument.
• The activate methods.
These methods activate the Service or Services specified by the method argument.
o It can only be invoked when the specified Service or Services are in the Inactive state.
o If it returns successfully, the specified Service or Services have transitioned to the Active
state.
These methods may throw the following exceptions.
o javax.slee.InvalidArgumentException.
This exception is thrown by the array-argument form of the method if the array parameter
is zero length or contains null or duplicate elements.
This exception is thrown if any of the specified Services are not in the Inactive state.
• The deactivate methods.
These methods deactivate the Service or Services specified by the method argument.
o It can only be invoked when the specified Service or Services are in the Active state.
o If it returns successfully, the specified Service or Services have transitioned to the Stop-
ping state. Eventually each deactivated Service will transition to the Inactive state after
all SBB entities executing for the Service have completed processing (see Section
2.2.17).
This exception is thrown by the array-argument form of the method if the array parameter
is zero length or contains null or duplicate elements.
This exception is thrown if the any of the specified Services are not in the Active state.

Chapter 14
Management
• The deactivateAndActivate methods.

These method deactivate the Service or Services specified by the first argument and activate the
Service or Services specified by the second argument, in a single operation. These methods can be
used to facilitate a Se rvice upgrade. For example a currently running Service can be deactivated
and drained while a new Service is activated to take over processing of new activities.
o It can only be invoked when the Service or Services that are to be deactivated are in the
Active state, and the Service or Services that are to be activated are in the Inactive state.
o If it returns successfully, the Service or Services that are to be deactivated have transi-
tioned to the Stopping state, and the Service or Services that are to be activated have tran-
sitioned to the Active state.
This exception is thrown if the same Service is identified t o be both deactivated and acti-
vated. It is also thrown by the array-argument form of the method if either of the array
parameters is zero length or contains null or duplicate elements.
This exception is thrown if any of the Services identified by the first argument are not in
the Active state, or if any of the Services identified by the second argument are not in the
Inactive state.
• The getServiceUsageMBean method.
This method returns the Object Name of a ServiceUsageMBean object that can be invoked to
obtain the usage information of the Service specified by the id argument.
o It can be invoked when the Service is any operational state.
• The above methods may throw the following exceptions:
o javax.slee.UnrecognizedServiceException.
If the id, deActID or actID argument specifies a Service that is not installed in the
SLEE, then the method throws an UnrecognizedServiceException.
failure.
Exception.
14.8.1 ServiceState objects

The ServiceState class defines an enumerated type for the operational states of a Service. A singleton
instance of each enumerated value is guaranteed (via an implementation of the readResolve method,
see java.io.Serializable for more details), so that equality tests using == are always evaluated
correctly. For convenience an integer representation of ServiceState objects is also available.
The following singleton objects define the valid argument or return values for ServiceState objects.
• INACTIVE
• ACTIVE
• STOPPING
Chapter 14
Management
The public contents of the ServiceState class is as follows:

public final class ServiceState implements java.io.Serializable {

// singletons
public static final SleeState INACTIVE …;
public static final SleeState ACTIVE …;
public static final SleeState STOPPING …;
public static final int SERVICE_INACTIVE …;
public static final int SERVICE_ACTIVE …;
public static final int SERVICE_STOPPING …;
// methods
public boolean isInactive() { … }
public boolean isActive() { … }
public boolean isStopping() { … }
public static ServiceState fromInt(int state)

}
• Each of the is<State> methods determines if this ServiceState object represents the
<State> operational state, and is equivalent to (this == <STATE>). For example, the is-
Active method determines if this ServiceState object represents the Active operational
state and is equivalent to (this == ACTIVE).
• The fromInt and toInt methods allow conversion between the ServiceState object form
and numeric form.
• The fromInt method throws a java.lang.IllegalArgumentException if the state
argument is not one of the three integer state representations.
14.9 ServiceUsageMBean interface

The ServiceUsageMBean interface defines the management interface used to interact with SBB usage
parameter sets for SBBs in a Service. It defines the methods to create, lookup, and remove SBB usage
parameter sets from SBBs in the Service.
This interface can also be used to obtain the JMX Object Name of SBB Usage MBean objects (see Section
14.10). SBB Usage MBean objects are used by management clients to query and reset the usage parameters
of a single SBB usage parameter set.
SBB usage parameter sets are persistent, i.e. they continue exist after SLEE restarts. However, the SLEE
specification does not specify whether the values of the usage parameters within the SBB usage parameter
sets are persistent or durable across SLEE restarts.
A ServiceUsageMBean object serves a particular Service. In other words, it is used to manipulate the
SBB usage parameter sets that are maintained by the SLEE for the Service.
The Object Name of a ServiceUsageMBean object for a particular Service may be obtained by invok-
ing the getServiceUsageMBean method on a ServiceManagementMBean object (see Section
14.6) and passing the Service identifier of the Service as an argument to this method.
The ServiceUsageMBean interface is as follows:

Chapter 14
Management
import javax.slee.InvalidSArgumentException;
import javax.slee.UnrecognizedSbbException;
import javax.slee.usage.UnrecognizedSbbParameterSetNameException;
public interface ServiceUsageMBean {

public ServiceID getService()
public void createUsageParameterSet(SbbID sbbId, String name)
UnrecognizedSbbException,
UsageParameterSetNameAlreadyExistsException,
public void removeUsageParameterSet(SbbID sbbId, String name)
UnrecognizedUsageParameterSetNameException,
public String[] getUsageParameterSets(SbbID sbbID)
public ObjectName getSbbUsageMBean(SbbID sbbId)
public ObjectName getSbbUsageMBean(SbbID sbbId, String name)
UnrecognizedUsageParameterSetNameException,
public void resetAllUsageParameters(SbbID sbbID)
public void resetAllUsageParameters()
public void close()
}
• The getService method.
This method returns a ServiceID object that identifies the Service that this ServiceUsage-
MBean object represents.
• The createUsageParameterSet method.
Create a new named SBB usage parameter set for the SBB specified by the sbbID argument with
the name specified by the name argument (within the Service represented by the Service-
UsageMBean object).
This method may throw the following exceptions.
o javax.slee.management.UsageParameterSetNameAlreayExistsEx-
ception.
This exception is thrown if the SBB usage parameter set identified by name already e x-
ists for the SBB identified by the sbbId parameter.
This exception is thrown if the name argument does not specify a valid SBB parameter
Chapter 14
Management
set name (see Section 0) or the SBB specified by the sbbId argument identifies an SBB
installed in the SLEE and is member of the Service presented by the ServiceUsageM-
Bean object but the SBB does not define an SBB Usage Parameters interface.
• The removeUsageParameterSet method.
Remove the named SBB usage parameter set that belongs to the SBB specified by the sbbID ar-
gument and the Service represented by the ServiceUsageMBean object with the name speci-
fied by the name argument.
o javax.slee.usage.UnrecognizedUsageParameterSetNameException.
This exception is thrown if the SBB usage parameter set identified by name does not cor-
respond to an SBB usage parameter set that exists for the SBB specified by the sbbId
parameter.
• The getUsageParameterSets method.
This method returns a list containing the names of the named SBB usage parameter sets that be-
long to the SBB specified by the sbbID argument and the Service represented by the Ser-
viceUsageMBean object.
• The getSbbUsageMBean methods.
These methods return the Object Name of an SBB Usage MBean object. The one-argument form
of this method returns an SBB Usage MBean object that provides management access to the de-
fault SBB usage parameter set for the SBB specified by the sbbID argument (within the Service
represented by the ServiceUsageMBean object). The two-argument form of this method re-
turns an SBB Usage MBean object that provides management access to the specified named SBB
usage parameter set.
These method may throw the following exception.
o javax.slee.usage.UnrecognizedUsageParameterSetNameException.
This exception is thrown by the two -argument form of this method if the SBB usage pa-
rameter set identified by name does not correspond to an SBB usage parameter set that
exists for the SBB specified by the sbbId parameter.
• The resetAllUsageParameters methods.
These methods reset all usage parameters in the default SBB usage parameter set and all named
SBB usage parameters sets. The one-argument form of this method resets the usage parameters of
only the SBB specified by the sbbID argument argument (within the Service represented by the
ServiceUsageMBean object). The zero-argument form of this method resets the usage pa-
rameters of all SBBs within the Service represented by the ServiceUsageMBean object. The
SLEE sets counter-type usage parameters to zero and removes all samples from sample-type usage
parameters.
• The close method.
A management client invokes this method to tell the SLEE that the ServiceUsageMBean ob-
ject is no longer required. The implementation of this method is free to deregister the Service Us-
age MBean object from the MBean Server. The management client must assume that the Object
Name it had for this Service Usage MBean object is no longer valid.
o javax.slee.UnrecognizedSbbException.
The method throws this exception if the sbbID argument does not identify an SBB in-
stalled in the SLEE or the SBB is not a member of the Service that is represented by the
ServiceUsageMBean object.

Chapter 14
Management
The method throws this exception if the sbbID argument identifies an SBB installed in
the SLEE that is a member of the Service that is represented by the ServiceUsageM-
Bean object but does not define an SBB Usage Parameters interface.
failure.
Exception.
14.10 SBB Usage MBean

The external management interface for accessing an SBB usage parameter set is defined by the SBB Usage
MBean interface. The SLEE generates an SBB Usage MBean interface for each SBB Usage Parameters
interface.
Logically, the SLEE maintains an instance of the SBB Usage MBean interface, also known as an SBB Us-
age MBean object, for each SBB usage parameter set. Using this SBB Usage MBe an object, the manage-
ment client can observe the usage parameters of the SBB usage parameter set and register with the SBB
Usage MBean object to receive usage notifications from these usage parameters.
The UsageNotification class defines the information conveyed in each usage notification. The base
SbbUsageMBean interface also specifies the notification type emitted by an SbbUsageMBean object.
The notification type for all usage notifications is “javax.slee.management.usage”. Each usage notification
is emitted as a UsageNotification object.
Usage notifications must only be emitted by an SBB Usage MBean object after updates to usage parame-
ters have been applied. For example, if a usage notification is emitted by an SBB Usage MBean object to a
notification listener, informing it that a new sample has been added to a sample-type usage parameter,
management clients must be able to query the SBB Usage MBean object and obtain statistics for that sam-
ple-type usage parameter that include the sample value contained in the notification.
A management client can use the SLEE specification defined usage notification filters to filter usage notifi-
cations. The SLEE specification defines the following usage notification filters:
• UsageUpdatedFilter.
This allows usage notifications of a particular usage parameter instance to pass.
• UsageOutOfRangeFilter.
This allows usage notifications of a particular usage parameter instance to pass if the value of the
usage p arameter is outside a given range.
• UsageThresholdFilter class.
This requires the value of a particular usage parameter instance to cross a threshold in either the
positive or negative direction before usage notifications relating to the usage parameter instance
are passed.
The SLEE generates the SBB Usage MBean interface and its implementation class, the SBB Usage MBean
class, when the SBB is deployed.
14.10.1 Requirements for the SBB Usage MBean interface

The following are the requirements for the SBB Usage MBean interface:

Chapter 14
Management
• The SBB Usage MBean interface must include in its definition all the methods defined in the in-
terface javax.slee.usage.SbbUsageMBean, either by directly or indirectly inheriting
from SbbUsageMBean interface or by including the operations defined in the SbbUsageM-
Bean interface in its dynamic interface.
• There is corresponding usage parameter accessor method in the SBB Usage MBean interface for
each usage parameter name defined in the SBB Usage Parameters interface (see Section 14.10.2).
14.10.2 Requirements for the usage parameter accessor method

The method signatures of the two forms of usage parameter accessor methods are as follows:
// counter-type accessor method
public long get<usage parameter name>(boolean reset)
// sample-type accessor method

public SampleStatistics get<usage parameter name>(boolean reset)
The following are the requirements for each usage parameter accessor method.
• There is a usage parameter accessor method for each usage parameter name declared in the SBB
Usage Parameters interface of the SBB.
• The method name of the this accessor method is the lowest-level usage parameter name with the
first letter uppercased and prefixed by “get”.
• The return type of this accessor method depends on the usage parameter type associated with the
usage parameter name.
o The return type is long if the usage parameter name is associated with counter-type us-
age parameters.
o The return type is javax.slee.usage.SampleStatistics if the usage parame-
ter name is associated with sample -type usage parameters.
• The accessor method returns the current value of the usage parameter. The value is a number for a
counter-type usage parameter and a SampleStatistics object for a sample -type usage pa-
rameter.
• If the reset argument is true, the SLEE will reset the usage parameter value before the requested
operation returns. The returned result is always the pre-reset value of the usage parameter. The
SLEE should implement this method as an atomic operation (with respect to concurrent access and
updates to the usage parameter being reset.)
• This method may throw a java x.slee.management.ManagementException if the re-
quested operation cannot be completed successfully.
14.10.2.1 SampleStatistics interface

The SampleStatistics interface provides basic statistical information about a sample-type usage p a-
rameter.
The SampleStatistics interface is as follows:
package javax.slee.usage;
public interface SampleStatistics {

public long getSampleCount();
public long getMinimum();
public long getMaximum();
public double getMean();
}

Chapter 14
Management
• The getSampleCount method.

This method returns the number of samples accumulated for the usage parameter. When the usage
parameter is reset this count returns to zero.
• The getMinimum method.
This method returns the minimum sample value recorded for the usage parameter. If the sample
count for this usage parameter is zero this method returns Long.MAX_VALUE.
• The getMaximum method.
This method returns the maximum sample value recorded for the usage parameter. If the sample
count for this usage parameter is zero this method returns Long.MIN_VALUE.
• The getMean method.
This method returns the mean of the sample values recorded for the usage parameter. If the sam-
ple count for this usage parameter is zero this method also returns zero.
14.10.3 Requirements for the SBB Usage MBean class

The SLEE implements an SBB Usage MBean class for each SBB that declares an SBB Usage Parameters
interface. An SBB Usage MBean object allows a management client to access an SBB usage parameter set
belonging to the SBB. Each SBB Usage MBean object represents an SBB usage parameter set. The man-
agement client invokes the SBB Usage MBean object to access and reset the usage parameters within the
SBB usage parameter set. It can also register to receive usage notifications for usage parameters that belong
to the SBB usage parameter set.
The following are the requirements for the SBB Usage MBean class:
• The SBB Usage MBean class must be implemented in accordance with the JMX 1.0 specification.
• The SBB Usage MBean class implements a standard MBean, a dynamic MBean, or a model
MBean but must present the SBB Usage MBean interface that is constructed using the rules speci-
fied in Section 14.10.1 to the MBean Server.
• The SBB Usage MBean class must implement all the methods defined in the javax.slee.us-
age.SbbUsageMBean interface. Section 14.10.4 describes each of these methods.
• The SBB Usage MBean class must implement all the usage parameter access methods of the SBB
Usage MBean interface.
• As an SBB Usage MBean class can emit notification, it must implement the JMX javax.ma-
nagement.NotificationBroadcaster interface. It must conform to the rules in Section
14.2.1.
• The SBB Usage MBean class may use javax.slee.management.ManagementExcep-
tion to report errors to the management client when the requested operation fails due to a sys-
tem-level problem.
14.10.4 SbbUsageMBean interface

All SBB Usage MBean classes implement the javax.slee.usage.SbbUsageMBean interface. The
SbbUsageMBean interface is as follows:
public interface SbbUsageMBean {

public static final String USAGE_NOTIFICATION_TYPE =
"javax.slee.management.usage";
public ServiceID getService() throws ManagementException;
public SbbID getSbb() throws ManagementException;

Chapter 14
Management
public String getUsageParameterSet() throws ManagementException;

public void resetAllUsageParameters() throws ManagementException;
public void close() throws InvalidStateException, ManagementException;
}
• The getService method.
This method returns the Service identifier of the Service containing the SBB usage parameter set
represented by the SBB Usage MBean object.
• The getSbb method.
This method returns the SBB identifier of the SBB containing the usage parameter set represented
by the SBB Usage MBean object.
• The getUsageParameterSet method.
This method returns the name of the SBB usage parameter set represented by the SBB Usage
MBean object. If the SBB Usage MBean object represents the default SBB usage parameter set for
an SBB, this method returns null.
• The resetAllUsageParameters method.
This method resets the values of all the usage parameters within the SBB usage parameter set rep-
resented by the SBB Usage MBean object.
• The close method.
A management client invokes this method to tell the SLEE that the SBB Usage MBean object is
no longer required. The implementation of this method is free to deregister the SBB Usage MBean
object from the MBean Server. The management client must assume that the Object Name it had
for this SBB Usage MBean object is no longer valid.
This method throws this exception if notification listeners are still attached to the SBB
Usage MBean object.
• These methods throw a javax.slee.management.ManagementException if the re-
quested operation cannot be performed due a system-level failure.
14.10.5 UsageNotification class

The public interface of the UsageNotification class is as follows:
public class UsageNotification extends Notification {

public UsageNotification(SbbUsageMBean notificationSource,
ServiceID service, SbbID sbb,
String sbbParameterSetName, String parameterName,
boolean counter, long value,
long sequenceNumber, long timeStamp){ … }
public final ServiceID getService { … }
public final SbbID getSbb () { … }
public final String getUsageParameterSetName() { … }
public final String getUsageParameterName() { … }
public final Boolean isCounter() { … }
public final long getValue() { … }
}

Chapter 14
Management
The UsageNotification class inherits all the attributes of the base Notification class and adds
the following attributes specific to usage notifications.
• The service attribute.
This attribute specifies the Service identifier of the Service named by the top most level scoped
name of the usage parameter that caused this usage notification to the emitted.
• The sbb attribute.
This attribute specifies the SBB identifier of the SBB named by the second level scoped name of
the usage parameter that caused this usage notification to the emitted.
• The usageParameterSetName attribute.
This attribute specifies the name of the SBB parameter set containing the usage parameter that
caused this usage notification to the emitted. If the usage parameter resides in the default SBB us-
age parameter set of an SBB, this method returns null.
• The usageParameterName attribute.
This attribute specified the name of the usage parameter that was updated.
• The counter attribute.
This boolean attributes indicates whether the usage parameter that caused the usage notification to
the emitted is a counter-type usage parameter (if counter is true) or a sample -type usage pa-
rameter (if counter is false).
• The value attribute.
If counter is true, this attribute provides the accummulated value of the counter-type usage
parameter that caused this usage notification to be emitted. If counter is false, this attribute
provides the the sample value of the sample -type usage parameter that caused this usage notifica-
tion to be emitted.
The semantics of the equals and hashCode methods are as follows:
Two UsageNotification objects are equivalent, i.e. usageOne.equals(usageTwo), if
their service, sbb, usageParameterSetName, usageParameterName, and counter
attributes are equal, as determined by their corresponding equals methods.
This method returns the exclusive or’ed hash codes of the service, sbb, usageParameter-
SetName, and usageParameterName attributes.
14.10.6 UsageUpdatedFilter class

The UsageUpdatedFilter class allows the usage notifications of the usage parameter specified by the
serviceID, sbbID and paramName arguments to the constructor of this filter class to pass. More pre-
cisely, a UsageUpdatedFilter object allows a usage notification t to be emitted if
t.getServiceID().equals(serviceID), t.getSbb().equals(sbbID), and
t.getUsageParameterName().equals(paramName), where serviceID, sbbID, and pa-
ramName are the constructor parameters for the notification filter. The filter ignores the SBB usage pa-
rameter set the notification comes from.
The public interface of the UsageUpdatedFilter class is as follows:
import javax.management.NotificationFilter;

Chapter 14
Management
public class UsageUpdatedFilter implements NotificationFilter {

public UsageUpdatedFilter(ServiceID serviceID, SbbID sbbID,
String paramName) { … }
public boolean isNotificationEnabled(Notification notification) { … }
}
14.10.7 UsageOutOfRangeFilter class

The UsageOutOfRangeFilter class allows usage notifications of the usage parameter specified by the
serviceID, sbbID and paramName arguments to the constructor of this filter class to pass if the value
of the usage parameter is outside the given range. This is achieved by comparing the current value of the
usage parameter to a low value and a high value. If the current value is less than the low level or greater
than the high value, the usage notification is allowed to pass through the filter. This filter ignores the SBB
usage parameter set the notification comes from.
The public interface of the UsageOutOfRangeFilter class is as follows:
public class UsageOutOfRangeFilter implements NotificationFilter {

public UsageOutOfRangeFilter(ServiceID serviceID, SbbID sbbID,
String paramName,
long lowValue, long highValue) { … }
}
14.10.8 UsageThresholdFilter class

The UsageThresholdFilter class requires the value of the specified usage parameter specified by the
serviceID, sbbID and paramName arguments to the constructor of this filter class to cross a threshold
value in either the positive or negative direction before the usage notifications relating to this usage pa-
rameter are passed. This is achieved by comparing the previous value of the usage parameter to the current
value of the usage parameter. If the specified threshold value lies between the previous value and the cur-
rent value then the usage notification is allowed to pass through the filter. The high and low threshold val-
ues are supplied to the UsageThresholdFilter object’s constructor. This filter ignores the SBB usage
parameter set the notification comes from.
public class UsageThresholdFilter implements NotificationFilter {

public UsageThresholdFilter(ServiceID service, SbbID sbbID,
String paramName, long threshold) { … }
}
14.11 ProfileProvisioningMBean interface

The ProfileProvisioningMBean interface defines the management API for managing the SLEE's
provisioned data. It can be used to:
• Create, delete and rename Profile Tables.
• Add and remove Profiles from Profile Tables.
Chapter 14
Management
• Obtain the JMX Object Name of the default Profile for a Profile Table.
• Get the names of all Profile Tables in the SLEE.
• Get the names of all Profiles in a specific Profile Table.
• Obtain the JMX Object Name of a specific Profile within a Profile Table using the unique name of
the Profile.
• Obtain the JMX Object Names of a set of Profiles within a Profile Table using an indexed attrib-
ute.
The ProfileProvisioningMBean interface is as follows:
import javax.slee.InvalidArgumentException;
import javax.slee.profile.AttributeNotIndexedException;
import javax.slee.profile.AttributeTypeMismatchException;
import javax.slee.profile.ProfileAlreadyExistsException;
import javax.slee.profile.ProfileTableAlreadyExistsException;
import javax.slee.profile.UnrecognizedProfileNameException;
import javax.slee.profile.UnrecognizedProfileSpecificationException;
import javax.slee.profile.UnrecognizedProfileTableNameException;
public interface ProfileProvisioningMBean {

public void createProfileTable(ProfileSpecificationID profileSpecID,
String newProfileTableName)
UnrecognizedProfileSpecificationException,
ProfileTableAlreadyExistsException,
public void removeProfileTable(String profileTableName)
public void renameProfileTable(String profileTableName,
String newProfileTableName)
ProfileTableAlreadyExistsException,
public ProfileSpecificationID getProfileSpecification(String profileTableName)
public ObjectName getDefaultProfile(String profileTableName)
public ObjectName createProfile(String profileTableName, String newProfileName)
ProfileAlreadyExistsException,
public void removeProfile(String profileTableName, String profileName)
UnrecognizedProfileNameException,
public ObjectName getProfile(String profileTableName, String profileName)

Chapter 14
Management
UnrecognizedProfileNameException,
public Collection getProfileTables()
public Collection getProfiles(String profileTableName)
public Collection getProfilesByIndexedAttribute(String profileTableName,
}
• The createProfileTable method.
This method creates a Profile Table with the name specified by the newProfileTableName
argument from the Profile Specification specified by the profileSpecID argument.
• The removeProfileTable method.
This method deletes the Profile Table identified by the profileTableName argument.
• The renameProfileTable method.
This method renames the Profile Table identified by the profileTableName argument to the
name specified by the newProfileTableName argu ment.
• The getProfileSpecification method.
This method returns a ProfileSpecificationID object that identifies the Profile Specifica-
tion of the Profile Table specified by the profileTableName argument.
• The getDefaultProfile method.
This method gets the JMX Object Name of a Profile MBean object for the default Profile of the
Profile Table specified by the profileTableName argument. There will always be a default
Profile for a Profile Table.
• The createProfile method.
This method gets the JMX Object Name of a modifiable Profile MBean object. When the Profile
MBean object commits successfully, the SLEE creates and adds a Profile with the name specified
by the newProfileName argument to the Profile Table specified by the profileTableName
argument. Before the Profile MBean object commits, the Profile name specifed by the newPro-
fileName argument does not exist and cannot be accessed by SBBs or through the Pro-
fileProvisioningMBean interface.
• The removeProfile method.
This method removes the Profile specified by the profileName argument from the Profile Ta-
ble specified by the profileTableName argument.
• The getProfile method.
This method gets the JMX Object Name of a Profile MBean object for the Profile identified by the
profileName argument in the Profile Table specified by the profileTableName argument.
This method does not provide access to a Profile that is in the process of being created before the
Profile MBean object returned by the createProfile method corresponding to the Profile
commits.
• The getProfileTables method.
This method returns a Collection object that contains all the names of the Profile Tables that
are installed in the SLEE.

Chapter 14
Management
• The getProfiles method.

This method returns a Collection object that identfies all the Profiles in the Profile Table iden-
tified by the profileTableName argument. The default Profile of the specified Profile Table is
not considered to be in the Profile Table and will not be included in the collection since the default
Profile does not have a Profile identifier.
• The getProfilesByIndexedAttribute method.
This method returns a Collection object that identifies the Profiles in the Profile Table identi-
fied by the profileTableName argument that satisfies the search criteria specified by the at-
tributeName and attributeValue arguments. The attributeName attribute identifies
the indexed attribute searched and the attributeValue argument identifies the value to look
for in the specified attribute.
o If the Java type of the attribute specified by the attributeName argument is not an ar-
ray type, a Profile satisfies the search criteria if the value stored in the specified attribute
is equal to the value specified by the attributeValue argument. If the Java type of
the indexed attribute is not a primitive Java type, the appropriate Java type of the at-
tributeValue argument must be the same as the Java type of the indexed attribute. If
the Java type of the indexed attribute is a primitive Java type, the appropriate Java type of
the attributeValue argument must be the Java wrapper class for the primitive type
of the indexed attribute.
o If the Java type of the attribute specified by the attributeName argument is an array
type, a Profile satisfies the search criteria if any element of the array object stored in the
specified attribute is equal to the value specified by the attributeValue argument. If
the Java type of the array element is not a primitive Java type, the appropriate Java type
of the attributeValue argument must be the same as the Java type of the arra y ele-
ment. If the Java type of the array element is a primitive Java type, the appropriate Java
type of the attributeValue argument must be the Java wrapper class for the primi-
tive type of the array element.
o If the Java type of the attributeValue argument is not an appropriate type for the
indexed attribute, then this method throws a javax.slee.profile.Attribute-
TypeMismatchException.
The default Profile of the specified Profile Table is not considered to be in the Profile Table and
If the newProfileTableName argument, the newProfileName a rgument, or the
attributeValue argument is invalid (see Section 10.1.2), the method throws an In-
validArgumentException.
This exception may also be thrown if there is an attempt to create a new Profile Table
with a new Profile Table name that is also referenced by an installed Service and the Pro-
file Specification of the create request is different from the Address Profile Specification
specified by the root SBB of the Service.
For example, FooSBB specifies FooProfileSpec as its Address Profile Specification.

FooSBB is FooService’s root SBB. If FooService specifies FooAddresses as the name of
its Address Profile Table, then the Profile Specification of FooAddresses is implicitly
bound to FooProfileSpec. If there is an attempt to create a Profile Table named FooAd-
dresses with a different Profile Specification, this exception may be thrown.

Chapter 14
Management
Similarly, this exception may also be thrown if there is an attempt to rename an existing
Profile Table to a new Profile Table name that is also referenced by an installed Service
and the Profile Specification of the rename request is different from the Address Profile
Specification specified by the root SBB of the Service.
o javax.slee.profile.UnrecognizedProfileSpecificationExceptio
n.
If the profileSpecID argument does not identify a Profile Specification recognized
by the SLEE, the method throws an UnrecognizedProfileSpecification-
Exception.
o javax.slee.profile.UnrecognizedProfileTableNameException.
If the profileTableName argument does not identify a Profile Table recognized by
the SLEE, the method throws an UnrecognizedProfileTableNameException.
o javax.slee.profile.UnrecognizedProfileNameException.
If the profileTableName argument identifies a valid Profile Table and the pro-
fileName argument does not identify a Profile in the identified Profile Table, then the
method throws an UnrecognizedProfileNameException.
o javax.slee.profile.UnrecognizedAttributeException.
If the attributeName argument does not identify an attribute of the Profile Table
specified by the profileTableName argument, then the method throws an Unre-
cognizedAttributeException.
o javax.slee.profile.ProfileTableAlreadyExistsException.
If the newProfileTableName argument identifies a Profile Table that is already in -
stalled in the SLEE, the method throws a ProfileTableAlreadyExistsExcep-
tion.
o javax.slee.profile.ProfileAlreadyExistsException.
If the newProfileName argument identifies a Profile that already exists in the Profile
Table identified by the profileTableName argument, then the method throws a
ProfileAlreadyExistsException.
o javax.slee.profile.AttributeNotIndexedException.
If the attributeName argument identifies an attribute that is not indexed, then the
method throws an AttributeNotIndexedException.
failure.
Exception.
14.11.1 Collection objects

The getProfileTableNames method returns Collection objects that contain java.la-
ng.String objects. The getProfiles and getProfilesByIndexedAttribute methods return
Collection objects that contain ProfileID (Profile identifier) objects.

Chapter 14
Management
The SLEE specification does not specify whether the Collection object returned by one of these meth-
ods are mutable. If there are mutations, these mutations have no effect on the SLEE, i.e. the SLEE does not
add or remove Profile Tables or Profiles when these Collection objects are modified.
The SLEE specification does not specify whether the Collection object returned by one of these meth-
ods and the Iterator objects obtained from the Collection object remain consistent across concurrent
modifications to the Profile database that hold the names. For example, if the Profile database is modified
after a Collection object has been obtained , then the Collection object may contain a different set
of names than in the Profile database.
Furthermore, if the SLEE implementation does not support concurrent modification, then an Iterator
object may throw a ConcurrentModificationException. An example of when this exception
may be thrown is as fo llows:
1. Invoke getProfileTables to get a Collection object containing all Profile Table names.
2. Invoke iterator on the Collection object to obtain an Iterator object.
3. Invoke removeProfileTable to remove a Profile Table.
4. Invoke next to get the next name on the Iterator object. If concurrent modification is not
supported, nextName may throw a ConcurrentModificationException.
14.12 Alarm Facility management interface

The AlarmMBean interface defines the management interface of the Alarm Facility (see Section 13.2). An
AlarmMBean object broadcasts alarm notifications for alarms generated by alarm sources. The Alarm-
Notification class defines the information conveyed in each alarm notification.
The AlarmMBean interface is an MBean interface that defines no management operations, but specifies
the notification type of alarm notifications emitted by an AlarmMBean object. The notification type for all
alarm notifications is “javax.slee.management.alarm”.
An AlarmMBean object emits alarm notifications for alarms originating from a number of sources includ-
ing (but not limited to):
• SBBs running in the SLEE
• Resource adaptors
• SLEE internal subsystems
The concrete class that implements the AlarmMBean interface must extend the NotificationBroad-
caster interface even though the AlarmMBean interface does not extend the NotificationBroad-
caster interface (see Section 14.2.1).
A management client can use a notification filter to filter alarm notifications. The SLEE specification de-
fines a number of standard alarm notification filters:
• AlarmLevelFilter.
This filter only allows alarms of a certain severity or higher to pass to the notification listener.
• AlarmDuplicateFilter.
This filter suppresses equivalent alarm notifications that occur during a specified time period.
Only the first in the series of duplicates are passed on to the notification listener. The cycle restarts
when the time period expires.
• AlarmThresholdFilter.
This filter suppresses equivalent alarm notifications until a specified number have occurred within
a specified time period. If, within the same time period, the filter receives a further equivale nt
alarm notification, the notification is passed on to the notification listener and the cycle restarts.

Chapter 14
Management
The cycle also restarts when the time period from the first notification expires without a notifica-
tion being sent.
The Object Name of an AlarmMBean object may be obtained invoking the getAlarmMBean method on
a SleeManagementMBean object (see Section 14.6).
14.12.1 AlarmMBean interface

The AlarmMBean interface is as follows:
public interface AlarmMBean {

public static final String ALARM_NOTIFICATION_TYPE
= "javax.slee.management.alarm";
}
14.12.2 AlarmNotification class

The public interface of the AlarmNotification class is as follows:
import javax.slee.facilities.Level;
public class AlarmNotification extends Notification {

public AlarmNotification(AlarmMBean notificationSource, String alarmType,
Object alarmSource, Level level,
String message, Throwable cause,
public final String getAlarmType() { … }
public final Object getAlarmSource() { … }
public final Level getLevel() { … }
public final Throwable getCause() { … }
}
The AlarmNotification class inherits all the attributes of the base Notification class and adds
the following attributes specific to alarm notifications.
• The alarmType attribute.
This attribute specifies the alarm type of the alarm being generated. The alarm type is set by the
alarm source.
• The alarmSource attribute.
This attribute specifies the source of the alarm. The alarm source may be an SBB, a resource adap-
tor, or a subsystem within the SLEE. If the alarm source is an installed component, the alarm-
Source object should be the component’s identifier object. If the alarm source is a SLEE
MBean, the alarmSource object should be the Object Name of the MBean. Otherwise the
alarm source may be null if the alarm source is a SLEE subsystem that has no visible identity. In
this case the alarmType attribute should clearly state the subsystem that generated the alarm.
• The level attribute.
This attribute specifies the alarm level of the ala rm represented by the alarm notification.
• The cause attribute.
This attribute is typically used to propagate an exception in the alarm notification. The value of
this attribute is null if the source of the alarm notification does not provide a value.
The object that generates an alarm (the alarm source) provides the values for the alarm notification’s
alarmType, alarmSource, level, message and timeStamp attributes. The AlarmMBean object

Chapter 14
Management
that generates the alarm notification provides the values for the notification’s type, source and se-
quenceNumber attributes. (The AlarmNotification class inherits the type, message and
timeStamp attributes from the base Notification interface.)
Two AlarmNotification objects are equivalent, i.e. alarmOne.equals(alarmTwo), if
their alarmType, alarmSource, level , and message attributes are equal, as determined
by their corresponding equals methods.
This method returns the has h code of the message attribute.
14.12.3 AlarmLevelFilter class

The AlarmLevelFilter class filters alarm notifications based on the severity of the alarm level in the
notification. Only alarm notifications of the specified severity level or greater will be a llowed through this
filter (see Section 13.2.2 for the ordering of different alarm levels).
The public interface of the AlarmLevelFilter class is as follows:
public class AlarmLevelFilter implements NotificationFilter {

public AlarmLevelFilter(Level minLevel) { … }
}
14.12.4 AlarmDuplicateFilter class

The AlarmDuplicateFilter class suppresses equivalent alarm notifications that occur during a speci-
fied time period. Only the first in a series of equivalent alarm notifications is allowed through this filter.
When the specified period of time elapses after the first notification, the cycle restarts and a subsequent
equivalent alarm notification is allowed through.
The public interface of the AlarmDuplicateFilter class is as follows:
public class AlarmDuplicateFilter implements NotificationFilter {

public AlarmDuplicateFilter(long period) { … }
}
14.12.5 AlarmThresholdFilter class

The AlarmThresholdFilter class filters equivalent alarm notifications until a specified number have
occurred within a specified time period. Once the threshold has been reached, the next equivalent alarm
notification is allowed through this filter and the cycle restarts. The cycle also restarts if the time period
from the first notification expires without the threshold being passed. This filter can be used to suppress
alarms that occur and then clear up spontaneously.
As an example, consider an AlarmThresholdFilter object with a threshold of five notifications and a
timeout of 500ms. On observation of an alarm notification that is not equivalent to any others it has seen,

Chapter 14
Management
the filter notes the current time and remembers the notification. If a further five equivalent alarm notifica-
tions are observed by the filter within the 500ms timeout period, the last notification is passed on to the
notification listener and the original notification is forgotten. If the 500ms time period expires without the
five equivalent notifications being observed, the original notification is forgotten and the cycle restarts.
This filter will suppress alarm notifications until at least six equivalent alarm notifications are observed
The public interface of the AlarmThresholdFilter class is as follows:
public class AlarmThresholdFilter implements NotificationFilter {

public AlarmThresholdFilter(int threshold, long timeout) { … }
}
14.13 Trace Facility management interface

The TraceMBean interface defines the management interface of the Trace Facility (see Section 13.4). A
TraceMBean object broadcasts trace notifications for trace messages generated by trace message sources.
The TraceNotification class defines the information conveyed in each trace notification.
The TraceMBean interface is an MBean interface that defines methods to get and set the trace filter levels
for trace messages. It also specifies the notification type of trace notifications emitted by a TraceMBean
object. The notification type for all trace notifications is “javax.slee.management.trace”.
A TraceMBean object emits trace notifications for trace messages originating from a number of sources
including (but not limited to):
• SBBs running in the SLEE
• Resource adaptors
Trace notifications are generally used for messages that need to be conveyed to management clients such as
integrated development environments during SBB creation, rather than for general logging of information
generated by the SLEE. Typically the SLEE internal subsystems do not use the Trace Facility or Trace-
MBean objects to generate logging or tracing information, however the SLEE specification does not pro-
hibit a SLEE implementation from doing so.
The concrete class that implements the TraceMBean interface must extend the NotificationBroad-
caster interface even though the TraceMBean interface does not extend the NotificationBroad-
caster interface (see Section 14.2.1).
A management client can use a notification filter to filter trace notifications. The SLEE specification de-
fines one standard trace notification filter:
• TraceLevelFilter.
This filter only allows trace notifications of a certain trace level or higher to pass to the notifica-
tion listener.
The Object Name of a TraceMBean object may be obtained invoking the getTraceMBean method on
a SleeProviderMBean object (see Section 14.6).
14.13.1 TraceMBean interface

The TraceMBean interface is as follows:

Chapter 14
Management
public interface TraceMBean {

public static final String TRACE_NOTIFICATION_TYPE
= "javax.slee.management.trace";
public void setTraceLevel(ComponentID id, Level level)
public TraceLevel getTraceLevel(ComponentID id)
}
• The setTraceLevel method.
This method sets the trace filter level for the component identified b y the id argument to the trace
level specified by the level argument. A trace message emitted for a component at an equal or
higher trace level than that trace filter level set for that component causes a trace notification to be
generated by the TraceMBean object. Conversely, a trace message generated by a component at
a trace level that is less than the trace filter level set for that component does not cause a trace noti-
fication to be generated. If the trace filter level for a component is set to Level.OFF (see Section
13.3), then no trace notifications are generated for that component.
The SLEE specification does not specify whether the effects of the set trace filter level operations
must be persistent or durable across SLEE restarts.
• The getTraceLevel method.
This method returns the current trace filter level for the component specified by the id argument.
failure.
Exception.
• The default trace filter level for a component is LEVEL.OFF. This means that trace notifications
are not generated for a component unless the trace filter level is explicitly set to a different value.
14.13.2 TraceNotification class

The public interface of the TraceNotification class is as follows:
public class TraceNotification extends Notification {

public TraceNotification(TraceMBean notificationSource, String messageType,
Object messageSource, Level level,
String message, Throwable cause,

Chapter 14
Management

public final String getMessageType() { … }
public final Object getMessageSource() { … }
public final Level getLevel() { … }
public final Throwable getCause() { … }
}
The TraceNotification class inherits all the attributes of the base Notification class and adds
the following attributes specific to trace notifications.
• The messageType attribute.
This attribute specifies the message type of the trace message being generated. The message type
is set by the message source.
• The messageSource attribute.
This attribute specifies the source of the trace message. The message source may be an SBB, a
Service, or a resource adaptor. The messageSource object should be the source component’s
identifier object.
• The level attribute.
This attribute specifies the trace level of the trace message.
• The cause attribute.
This attribute is typically used to propagate an exception in the trace message. The value of this at-
tribute is null if the source of the trace message does not provide a value.
The object that generates a trace message provides the values for the trace notification’s messageType,
messageSource, level, message and timeStamp attributes. The TraceMBean object that gener-
ates the trace notification provides the values for the notification’s type, notificationSource and
sequenceNumber attributes. (The TraceNotification class inherits the type, message and
timeStamp attributes from the base Notification interface.)
Two TraceNotification objects are equivalent, i.e. traceOne.equals(traceTwo), if
their messageType, messageSource, level , and message attributes are equal, as deter-
mined by their corresponding equals methods.
This method returns the hash code of the message attribute.
14.13.3 TraceLevelFilter class

The TraceLevelFilter class filters trace notifications based on the trace level in each trace notifica-
tion. Only trace notifications of the specified trace level or higher will be allowed through this filter (see
Section 13.3 for the ordering of trace levels).
The public interface of the TraceLevelFilter class is as follows:
public class TraceLevelFilter implements NotificationFilter {

public TraceLevelFilter(Level minLevel) { … }
}

Chapter 14
Management
14.14 Security
Administrators acting in many different roles may manage the SLEE. For example, an Administrator may
be a Service Administrator, a Profile Table Administrator, or a SLEE Administrator. Access to the man-
agement operations of the SLEE must be carefully controlled while taking into consideration the different
roles of an Administrator. Diffe rent permissions can be granted to each role and the Administrator must be
authenticated within a role before they can be authorized to invoke the methods associated with that role.
The SLEE specification does not define any security roles, security access protocol, or security mecha-
nisms. It is the responsibility of the SLEE vendor to define a secure environment, either by defining a ven-
dor specific mechanism, or by utilizing a standard mechanism such as Java Authentication and Authoriza-
tion Service (JAAS). It is the responsibility of management client MLets to pass to the SLEE the relevant
authentication principals. A management client should expect to receive SecurityExceptions from
the SLEE if the Administrator does not have the appropriate permissions to execute a particular manage-
ment operation.

Chapter 15
Resource Adaptors
Chapter 15 Resource Adaptors

Resources are entities that represent and interact with other systems outside the SLEE, such as network
devices, protocol stacks, directories, and databases. These resources may or may not have Java APIs. Re -
sources with Java APIs currently include call agents supporting the Java Call Control (JCC) API, Par-
lay/OSA services supporting a Java API, various protocol stacks , and databases supporting the JDBC API.
These Java APIs define Java classes or interfaces to interact with the resource and to represent the events
emitted by the resource. For example, the Java Call Control API defines the JccCallEvent and
JccConnectionEvent interfaces to represent call and connection events. JccConnectionEvent
objects convey information about connection events such as connection alerting and connection connecting.
Resource adaptors adapt particular resources to the requirements of the SLEE. The APIs and design pat-
terns used between a resource, a resource adaptor and the SLEE are outside of the scope of this release of
the SLEE specification.
The SLEE architecture defines the following resource adaptor concepts.
• Resource adaptor type.
A resource adaptor type specifies the common definitions for a set of resource adaptors. It d efines
the Java interfaces implemented by the resource adaptors of the same resource adaptor type. Typi-
cally, a resource adaptor type is defined by an organization of collaborating SLEE or resource
vendors, such as the SLEE expert group. An Administrator installs resource adaptor types in the
SLEE.
• Resource adaptor.
A resource adaptor is an implementation of a particular resource adaptor type. Typically, a re -
source adaptor is provided either by a resource vendor or a SLEE vendor to adapt a particular re -
source implementation to a SLEE, such as a particular vendor’s implementation of a SIP stack. An
Administrator installs resource adaptors in the SLEE.
• Resource adaptor entity.
A resource adaptor entity is an instance of a resource adaptor. Multiple resource adaptor entities
may be instantiated from a single resource adaptor. Typically, an Administrator instantiates a re-
source adaptor entity from a resource adaptor installed in the SLEE by providing the parameters
required by the resource adaptor to bind to a particular resource. In the rest of this chapter, a re -
source adaptor entity may be used more broadly to encompass the resource (e.g. an instantiated
JAIN SIP protocol stack) and the resource adaptor entity that represents by the resource (e.g. the
entity that adapts the JAIN SIP protocol stack to the SLEE),
15.1 Resource adaptor type

A resource adaptor type declares the common characteristics of a set of resources and their resource adap-
tors.
Generally, two different resources with the same functional characteristics should have the same resource
adaptor type. For example, two different TCAP stacks may be installed in the same SLEE. If both of these
TCAP stacks implement the same JAIN TCAP API, then both TCAP stacks should have the same resource
adaptor type. If these TCAP stacks expose different TCAP APIs, they must have different resource adaptor
types.
Each resource adaptor type declares the following common characteristics:
• Event types.
The resource adaptor type declares the event types that are fired by resource adaptors of this re-
source adaptor type (see Section 8.1.7).
• Activities.
The resource adaptor type identifies the resource specific statemachines that emit events or mes-
sages .

Chapter 15
Resource Adaptors
• Activity interfaces and classes.

For each identified Activity, the resource adaptor type must define a Java object that represents the
Activity (see Section 7.2). The resource adaptor type declares the interfaces and/or classes of these
Activity objects. If a resource adaptor type maps an underlying resource’s Activity that is repre-
sented by a primitive Java type to a Java object, then this mapping should be well-documented.
• Activity object end conditions.
For each of the Activity interfaces and classes defined by the resource adaptor type, the conditions
that end an Activity object of the resource adaptor type must be well documented. Typical condi-
tions that end an Activity object are as follows:
o The underlying Activity ends, e.g. a call terminates when the all of the participants hang
up.
o A method is invoked that ends the Activity object is invoked, such as invoking the end-
Activity method on a NullActivity object (see Section 7.10.5.2).
o A method is invoked that indirectly causes the underlying Activity to end (see Section
7.3.4.3).
• Activity Context Interface Factory interface.
Each resource adaptor type defines an Activity Context Interface Factory interface (see Section
7.6.1). An object that implements the Activity Context Interface Factory interface can be bound
into the JNDI component environment of an SBB using a resource-adaptor-type-
binding element in the SBB’s deployment descriptor. An SBB uses this object to access the Ac-
tivity Context of a particular res ource adaptor’s Activity object13 . As resource adaptors and the
SLEE collaborate to implement this function, they can validate the Activity object.
• A resource adaptor interface.
Each resource adaptor type may optionally define a resource adaptor interface. (This resource
adaptor interface may be defined by the resource represented or may be synthesized by the re-
source adaptor type.) The resource adaptor interface must be declared as public. An object that
implements the resource adaptor interface can be bound into the JNDI component environment of
an SBB using a resource-adaptor-entity-binding element in the SBB’s deployment
descriptor. This object allows the SBB to invoke the resource adaptor entity represented by the re-
source adaptor object. For example, the JccProvider interface is an appropriate resource adap-
tor interface for JCC.
If a resource has more than one interface that should be made accessible via JNDI, then the re-
source adaptor type should define a wrapper interface that has accessor methods for these inter-
faces as the resource adaptor interface.
• Disallowed methods.
The resource adaptor type defines a set of methods that are defined by the underlying resource API
but cannot be invoked by components running in the SLEE. For example, the resource adaptor
type should disallow methods that affect event delivery and the location independence of SBBs.
For example, the JCC resource adaptor type should specify that the addConnectionLis-
tener, addCallListener, and setFilter methods are disallowed. When a dis allowed
method is invoked, the resource adaptor entity must throw a SecurityException.
15.1.1 Resource adaptor type identifiers

Similar to SBB and Service, a resource adaptor type is uniquely identified by the name, vendor, and version
of the resource adaptor type. Two resource adaptor types with same name, vendor, and version are consid-
ered to be the same resource adaptor type. Different resource adaptor types are assumed to be incompatible,
meaning that one cannot be substituted for another.
13
The resource adaptor entity that is respon sible for this Activity object is an instance of a resource adaptor that belongs to this
resource adaptor type.
Chapter 15
Resource Adaptors
15.1.2 Resource adaptor type deployment descriptor

A resource adaptor type deployment descriptor contains a resource-adaptor-type element. This
element contains at least the following sub-elements:
• A resource-adaptor-type-name element, a resource-adaptor-type-vendor
element, and a resour ce-adaptor-type-version ele ment.
These elements uniquely identify the resource adaptor type.
• A resource-adaptor-type-classes element.
o Zero or more activity-type elements.
The Java types of all the resource adaptor type’s Activity objects must be declared. Each
activity-type element declares one of these Java types. Each activity-type
element contains the following sub-elements:
This is an optional informational element. This element should document the
conditions that end Activity objects of this Java type.
§ An activity-type-name element.
This element identifies the name of the Java type. The Java type must be either
an interface or a class.
o An activity-context-interface-factory-interface element.
This element is optional. It contains the following sub-elements:
§ An activity-context-interface-factory-interface-name
element.
This element identifies the interface name of the Activity Context Interface Fac-
tory of the resource adaptor type.
o A resource-adaptor-interface element.
This element is optional. It specifies the Java type of the resource adaptor interface. Each
resource adaptor of this resource adaptor type provides an implementation of this re-
source adaptor interface, An SBB can bind an object of this Java type into its JNDI com-
ponent environment using a resource-adaptor-entity-binding element in the
SBB’s deployment descriptor. The resource-adaptor-interface element con-
tains the fo llowing sub-elements:
§ A resource-adaptor-interface-name element.
This element specifies the Java type of the resource adaptor interface.
• Zero or more event-type-ref elements.
Each event type that the resource type may fire must have an event-type-ref element. An
event-type-ref element references an event type. It contains following the sub-elements:
o An event-type-name element, an event-type-vendor element, and an
These elements uniquely identify an event type declared in an event-definition

Chapter 15
Resource Adaptors
element specified in another deployment descriptor. An event-definition element
declares an event type (see Section 8.3.1)
SLEE vendors may add additional sub-elements to the resource-adaptor-type element if required.
The resource adaptor type deployment descriptor described above is provisional and will be standardized in
a future JSR (such as a future SLEE JSR for the next version of the SLEE specification or a separate SLEE
Resource JSR).
15.1.3 Resource adaptor type packaging

The SBB Developer may distribute the classes of resource adaptor types in either source form or compiled
Java class files. These files and the resource adaptor type deployment descriptor may be distributed as sepa-
rate files, or in one or more jar files.
To ease distribution and deployable unit assembly, the SLEE specification recommends that these files be
distributed in a resource adaptor type jar file. The SLEE specification specifies the recommended organiza-
tion and content of a resource adaptor type jar file.
15.1.4 Resource adaptor type jar file

The resource adaptor type jar file is the standard format for the packaging of one or more resource adaptor
types. It must include the following:
• A resource adaptor type jar deployment descriptor.
o The resource adaptor type jar deployment descriptor is stored with the name META-
INF/resource-adaptor-type-jar.xml in the resource adaptor type jar file.
o The root element of the resource adaptor type jar deployment descriptor is a re-
source-adaptor-type-jar element. This element contains the following sub-
elements.
§ One or more resource-adaptor-type elements.
Each of these elements is a resource adaptor type deployment descriptor as de-
fined in Section 15.1.2.
• Class files of the resource adaptor types specified by the resource-adaptor-type elements
of the resource-adaptor-type-jar element.
o The resource adaptor type jar file must contain, either by inclusion or by reference, the
class files of the resource adaptor types.
o The resource adaptor type jar file must also contain, either by inclusion or by reference,
the class files for all the classes and interfaces that the Java types of the resource adaptor
types depend on, except J2SE classes and SLEE classes, classes contained in the event jar
files of the event types referenced by the resource adaptor types. This includes their su-
perclasses and superinterfaces, dependent classes, and the classes and interfaces used as
method parameters, results, and exceptions.
15.1.5 Resource adaptor type jar file example

The following example illustrates a resource adaptor type jar file that declares a resource adaptor type.
The deployment descriptor for the example resource adaptor type jar file is as follows:
<resource-adaptor-type-jar>
…
<resource-adaptor-type>
JCC

Chapter 15
Resource Adaptors
javax.csapi.cc.jcc
1.1
<resource-adaptor-type-classes>
<activity-type>
<activity-type-name>
javax.csapi.cc.jcc.JccCall
</activity-type-name>
</activity-type>
<activity-type>
<activity-type-name>
javax.csapi.cc.jcc.JccConnection
</activity-type-name>
</activity-type>
<activity-context-interface-factory-interface>
<activity-context-interface-factory-interface-name>
javax.csapi.cc.jcc.slee.JccActivityContextInterfaceFactory
</activity-context-interface-factory-interface-name>
</activity-context-interface-factory-interface>
<resource-adaptor-interface>
<resource-adaptor-interface-name>
javax.csapi.cc.jcc.JccProvider
</resource-adaptor-interface-name>
</resource-adaptot-interface>
</resource-adaptor-type-classes>
<event-type-ref>
<event-type-name>
javax.csapi.cc.jcc.JccConnectionEvent.CONNECTION_ALERTING
</event-type-name>
<event-type-vendor> javax.csapi.cc.jcc </event-type-vendor>
</event-type-ref>
…
</resource-adaptor-type>
</resource-adaptor-type-jar>
The content of the resource adaptor type jar file is as follows:

META-INF/resource-adaptor-type-jar.xml
…
javax/csapi/cc/jcc/slee/JccActivityContextInterfaceFactory.class
jcc.jar
…
15.2 Resource adaptor

A resource adaptor is a particular vendor’s implementation of a resource adaptor type. Each resource adap-
tor must identify the resource adaptor type it implements. A resource adaptor must implement exactly one
Typically, a resource adaptor contains code that interfaces an implementation of a resource to the SLEE.
For example, it contains code that hands event objects and Activity objects when events are fired, and code
that collaborates with the SLEE to manage Activity object life cycles.

Chapter 15
Resource Adaptors
15.2.1 Resource adaptor deployment descriptor

Each resource adaptor is declared by a resource adaptor deployment descriptor. Each resource adaptor de-
ployment descriptor contains a resource-adaptor element. This element contains at least the follow-
ing sub-elements:
• A resource-adaptor-name element, a resource-adaptor-vendor element, and a
resource-adaptor-version element.
These elements uniquely identify the resource adaptor.
• A resource-adaptor-type-ref element.
This element references a resource adaptor type. It contains the following elements:
o A resource-adaptor-type-name element, a resource-adaptor-type-
vendor ele ment, and a resource-adaptor-type-version element.
These elements uniquely identify a resource type declared in a resource-adaptor-
type element specified in another deployment descriptor. A resource-adaptor-
type element declares a resource adaptor type (see Section 15.1.2)
• A resource-adaptor-classes element.
This element contains sub-elements that identify the classes that implement this resource adaptor.
This release of the SLEE specification does not define the sub -elements of this element.
SLEE vendors may add additional sub-elements to the resource-adaptor element if required. The
resource adaptor deployment descriptor described above is provisional and will be standardized in a future
JSR (such as a future SLEE JSR for the next version of the SLEE specification or a separate SLEE Re-
source JSR).
15.2.2 Resource adaptor packaging

The SBB Developer may distribute the classes of resource adaptor in either source form or compiled Java
class files. These files and the resource adaptor deployment descriptor files may be distributed as separate
files, or in one or more jar files.
To ease distribution and deployable unit assembly, the SLEE specification recommends that these files be
distributed in a resource adaptor jar file. The SLEE specification specifies the recommended organization
and content of a resource adaptor jar file.
15.2.3 Resource adaptor jar file

The resource adaptor jar file is the standard format for the packaging of one or more resource adaptors. It
must include the following:
• A resource adaptor jar deployment descriptor.
o The resource adaptor jar deployment descriptor is stored with the name META-
INF/resource-adaptor-jar.xml in the resource adaptor jar file.
o The root element of the resource adaptor jar deployment descriptor is a resource-
adaptor-jar ele ment. This element contains the following sub-elements.
§ One or more resource-adaptor elements.
Each of these elements is a resource adaptor deployment descriptor as defined in
Section 15.2.1.
Chapter 15
Resource Adaptors
• Class files of the resource adaptors specified by the resource-adaptor elements of the re-
source-adaptor-jar element.
o The resource adaptor jar file must contain, either by inclusion or by reference, the class
files of the resource adaptors.
o The resource adaptor jar file must also contain, either by inclusion or by reference, the
class files for all the classes and interfaces that the Java types of the resource adaptors
depend on, except J2SE classes, SLEE classes, classes contained in the resource adaptor
type jar files of the resource adaptor types of the resource adaptors, classes contained in
the event jar files of the event types referenced by the resource a daptor types of the re-
source adaptors. This includes their superclasses and superinterfaces, dependent classes,
and the classes and interfaces used as method parameters, results, and exceptions.
15.2.4 Resource adaptor jar file example

The following example illustrates a resource adaptor jar file that declares a resource adaptor.
The deployment descriptor for the example resource adaptor jar file is as follows:
<resource-adaptor-jar>
…
<resource-adaptor>
<resource-adaptor-name> FooBar JCC </resource-adaptor-name>
<resource-adaptor-vendor> com.foobar </resource-adaptor-vendor>
<resource-adaptor-version> 10/10/20 </resource-adaptor-version>
JCC
javax.csapi.cc.jcc
1.1
<resource-adaptor-classes>
…
</resource-adaptor-classes>
</resource-adaptor>
</resource-adaptor-jar>
The content of the resource adaptor jar file is as follows:

META-INF/resource-adaptor-jar.xml
…
<class files of the resource adaptor>
…
15.3 Accessing Activity Context Interface Factories from within an SBB

An SBB can explicitly lookup an object that implements the Activity Context Interface Factory interface of
a resource adaptor type in its JNDI component environment. It can use this object to obtain Activity Con-
text Interface objects from the Activity objects created by resource adaptor entities of the resource adaptor
type. This requires a resource-adaptor-type-binding element in the SBB’s deployment descrip-
tor to bind an Activity Context Interface Factory object into the JNDI component environment of the SBB.
15.4 Accessing resource objects from within an SBB

In this section, a resource object refers to an object created by a resource adaptor entity. An SBB can obtain
access to a res ource object in the following ways.

Chapter 15
Resource Adaptors
• Looking up a resource object in the JNDI component environment of the SBB.

The SBB can explicitly lookup an object that implements the resource adaptor interface of the re-
source adaptor type in its JNDI component enviro nment. It can use this object to interact with the
resource adaptor entity. This requires a resource-adaptor-entity-binding element in
the SBB’s deployment descriptor to establish the resource adaptor entity binding in the JNDI
comp onent environment of the SBB.
• Receiving an Activity object (owned by an resource adaptor entity) embedded in event objects.
An SBB object of the SBB may receive an event fired by a resource adaptor entity. The event ob-
ject may contain direct or indirect references to Activity objects owned by the resource adaptor en-
tity. The SBB object can interact with the resource adaptor entity through one or more of these Ac-
tivity objects. This does not require a resource-adaptor-entity-binding element in
the SBB’s deployment descriptor. An SBB does not have to reference a resource adaptor entity or
resource adaptor type of the resource adaptor entity in its deployment descriptor to receive events
fired by the resource adaptor entity. For example, root SBB entities of this SBB will receive init ial
events from the resource adaptor entity if the resource adaptor entity fires events of the initial
event types of the SBB and these events are fired on addresses stored in the Address Profile Table
of the Service that specifies this SBB as its root SBB.
• Receiving input parameters passed through its SBB local interface.
15.4.1 Accessing multiple resource adaptor entities

An SBB may use multiple resource adaptor entities of the same resource adaptor type or different resource
adaptor types. The SBB Developer should specify the JNDI names of the resource adaptor objects (through
the resource-adaptor-object-name element) and resource adaptor type defined Activity Context
Interface Factory objects (through the activity-context-interface-factory-name element)
accessed by the SBB. In addition, the SBB Developer should also specify the requirements or properties of
the objects that should be bound to the specified JNDI names in the description element of the corre-
sponding resource-adaptor-entity-binding and resource-adaptor-type-binding
elements.
The Service Deployer uses these descriptions to bind the appropriate resource adaptor entities and resource
adaptor types to the specified JNDI names.
The SBB looks up the specified JNDI names for the resource adaptor objects and resource adaptor type
defined Activity Context Interface Factory objects that it requires.
15.4.2 Example code

This following example shows how an SBB may obtain a reference to two resource adaptor objects belong-
ing to two different resource adaptor entities of the same resource adaptor type, and obtain the SBB Activ-
ity Context Interface object for one of the Activity objects of this resource adaptor type.
The SBB deployment descriptor for this SBB is as follows:
<sbb>
…
<description>
This SBB expects the JCC 1.1 resource type to be
bound to the JNDI name specified below.
</description>
JCC
javax.csapi.cc.jcc
1.1

Chapter 15
Resource Adaptors
<activity-context-interface-factory-name>
slee/resource/jcc/1.1/activitycontextinterfacefactory
</activity-context-interface-factory-name>
<description>
This SBB expects a JCC 1.1 resource that has the
following properties to be bound to the JNDI name
specified below.
1. …
2. …
</description>
FooBarJCC
…
<description>
This SBB expects a JCC 1.1 resource that has the
following properties to be bound to the JNDI name
specified below.
1. …
2. …
3. …
4. …
</description>
CuckooJCC
…
</sbb>
The SBB code that accesses the resource adaptor objects, the Activity Context Interface Factory object of
these resource adaptor type of these resource adaptor entities, and obtains an SBB Activity Context Inter-
face object from a generic Activity Context Interface object is as follows.
…
// obtain the SBB component environment naming context.
…
// get first JCC resource adaptor object
JccProvider jcc1 = (JccProvider) myEnv.lookup("slee/resources/jcc/1.0b/jcc_1");
…
// get second JCC resource adaptor object
JccProvider jcc2 = (JccProvider) myEnv.lookup("slee/resources/jcc/1.0b/jcc_2");
…
// create a call on jcc1
JccCall call = jcc1.createCall();
…
// get ActivityContectInterfaceFactory object for JCC
JccActivityContextInterfaceFactory jccACIFactory =
(JccActivityContextInterfaceFactory)
myEnv.lookup("slee/resources/jcc/1.1/activitycontextinterfacefactory");
…
// get generic Activity Context Interface object for call
ActivityContextInterface ac = jccACIFactory.getActivityContext(call);
…

Chapter 15
Resource Adaptors
// get SBB Activity Context Interface object from
// generic Activity Context Interface object
FooSbbActivityContextInterface fooAC = asSbbActivityContextInterface(ac);
…
15.5 Event delivery semantics on newly created Activity objects

If within a single transaction an SBB entity invokes a method on a resource adaptor entity that creates a
new Activity object, the SBB entity attaches to the corresponding Activity Context , the transaction com-
mits, and the SBB entity can receive subsequent events emitted from the newly created Activity object, the
SLEE must deliver these events to the SBB entity (regardless of whether the resource is transactional or
not).
For example, an SBB entity creates a new Activity object in a transaction. Before the transaction commits,
the Activity object emits an event. The SBB entity attaches to the Activity Context of the Activity object
before the transaction commits. If the event is of an event type that the SBB entity can receive, then the
SLEE must deliver the event to the SBB entity after the transaction commits.
This means that the SLEE and the resource adaptor entity must coordinate to ensure that events emitted
from the time that an SBB entity creates an Activity object and attaches to the Activity Context of the Ac-
tivity object in a transaction to the time that the transaction commits are not “missed”.
Without this requirement, there may be a potential race condition between the time that the Activity object
is created and the time that the transaction commits in which events emitted by the Activity object will not
be delivered to the SBB entity.
15.6 Transaction context propagation

When a resource adaptor entity is invoked from within an SBB method invocation, whether the transaction
context of the SBB invocation is propagated to the resource adaptor entity is defined in Section 9.9.
Each resource adaptor type is expected to specify the transaction requirements (e.g. non-transactional, re-
quired, or mandatory transactional) for each method exposed by the interfaces and classes declared by the
Per method transaction requirements are likely to be specified in a similar manner to the Java Connector
Architecture specification or the EJB 2.0 specification in a future release of this specification or a future
SLEE Resource specification.
15.7 Resource adaptor entity firing an event

The SLEE must provide an API for a resource adaptor entity to pass events to the SLEE. This version of
the SLEE specification does not define this API. However, at least the following information must be
passed to the SLEE when a resource fires an event:
• The event object.
• The event type of the event.
• Either an Activity object (that represents the event’s Activity) or corresponding Activity Context.
In most cases, the resource adaptor entity will provide an Activity object.
• An optional Address object.
If provided, this object specifies the default address of the event.
15.8 Resource event filters

It is expected that a resource and the resource adaptor entity that represents the resource would collaborate
with the SLEE to set appropriate filters to ensure that events required by the Services installed and running
in the SLEE will be delivered to the SLEE. For e xample, when an address is added to the Address Profile
Table of a Service, the SLEE, its resources and resource adaptor entities must be able to install the appro-
priate event filters and triggers to make sure when an event that occurs on the address and belongs to one of

Chapter 15
Resource Adaptors
the initial event types of the root SBB of the Service is delivered to the SLEE. Similarly, the SLEE, its re-
sources and resource adaptor entities must collaborate to update event filters and triggers when SBB enti-
ties attach and detach from A ctivity Contexts, mask and unmask events, … etc.
15.9 Resource adaptor entity and Activity Context interactions

Since an Activity Context encapsulates an Activity object that is provided by a resource adaptor entity, the
resource adaptor entity must participate in the life cycle management of an Activity object and the Activity
object’s Activity Context. At the very high level, the SLEE is expected to interact with a resource adaptor
entity in the following ways to manage the life cycle of an Activity object and the Activity Context of the
Activity object.
• The SLEE and the resource adaptor entity collaborate to create the Activity Context for the Activ-
ity object. As a result of this collaboration, the SLEE knows the resource adaptor entity that is re-
sponsible for the life cycle of the Activity object. This allows the SLEE to inform the resource
adaptor entity of changes to the Activity object’s Activity Context that may influence the life cycle
of the Activity object.
• The SLEE informs the resource adaptor entity responsible for the Activity object when the Activ-
ity object’s Activity Context is no longer attached to any SBB entities and is no longer referenced
by any SLEE Facilities. This enables the resource adaptor entity to implicitly end the Activity ob-
ject when the Activity object’s Activity Context is no longer reachable (similar to how the SLEE
ends a NullActivity object implicitly, see Section 7.10.5.1).
• The resource adaptor entity informs the SLEE when an Activity object has ended. This allows the
SLEE to move the Activity object’s Activity Context to the Ending state (see Section 7.3.3).
• The SLEE informs the resource adaptor entity responsible for the Activity object when the Activ-
ity object’s Activity Context moves from the Ending state into the Invalid state. This allows the
resource adaptor entity to releas e any references to the Activity object’s Activity Context so that
the Activity Context can be reclaimed.

Appendix A
Event Router Formal Model
Appendix A Event Router Formal Model

A.1 Notation
Z is the set of integers. R is the set of real numbers.
P(s), where s is a set, is called the power set of s. It is defined as the set of all subsets of s
P( s) = {x : x ⊆ s}.
th
x i refers to the i component of the tuple x. If a component of a tuple x is itself a tuple, the notation ( xi ) j
indicates the jth component of the i th component of x. For example, if
x = (( a, b) , (c, d ))
then
( x1 ) 1 = a ,
( x1 ) 2 = b,
( x 2 )1 = c,
(x 2 )2 = d,
The minarg function is defined as follows:
f ( x) = y ∈ S such that f ( y) = xmin
min arg
x∈ S ∈ S f ( x)
A.2 Definitions
A.2.1 Events
Let EventType be the set of event types and let Event be the set of events. An event e is an ordered triple,
( e1 , e2 , e3 , e4 ) ∈ Z × EventType× ActivityContext × Address ,
where e1 is the identity of the event, e2 is the type of event, e3 is the Activity Context14 on which the event
was fired, and e4 is the SLEE-determined address for the event.
A.2.2 Child relations

Let ChildRelation be the set of child relations. A child relation cr is an ordered pair,
( cr1 , cr2 ) ∈ Z × SBBComponent ,
where cr1 is the default priority of the child relation and cr2 is the child SBBcomponent15 of the child rela-
tion.
A.2.3 SBB Components

Let SBBComponent be the set of all SBB components. An SBB component c is a 5-tuple
( c1 , c 2 , c3 , c 4 , c5 ) ∈ P(ChildRelation) × P( EventType)
× P( EventType) × P( EventType) × P( EventName)
14
ActivityContext is defined in Section A.2.7.
15
SBBComponent is defined in Section A.2.3.
Appendix A
where c1 is the set of child relations of the SBB component, c2 is the set of initial event types of the SBB
component, c3 is the set of received event types of the SBB component, c4 is the set of mask-on-attach
event types of the SBB component, and c5 is the set of mask-on-attach event names of the SBB comp o-
nent. For a given SBB component c,
c 2 , c4 ⊆ c3 .
A.2.4 Child relation objects

Let ChildRelationObject be the set of all child relation objects.
Let ExistingChildObject (t) be the set of child relation objects that are said to ‘exist’ at time t. A child rela-
tion object cro that exists at time t is an ordered pair,
( cro1, cro2 ) ∈ ChildRelation× P ( ExistingSBB (t)) ,
where cro1 is the child relation of the child relation object and cro 2 is the set of child SBB entities16 of the
child relation object.
A.2.5 SBB Entities

Let SBBEntity be the set of all SBB entities. An SBB entity x is an ordered triple,
( x1 , x2 , x3 ) ∈ Z × SBBComponent × P( Name) ,
where x1 is the identity of the SBB entity, x 2 is the type of the SBB entity, and x3 is a set containing the
convergence name 17 of the SBB entity.
We define
ExistingSBB(t ) : R α P( SBBEntity)
as a relation which defines the set of SBB entities that are said to ‘exist’ at time t. For each SBB entity
x ∈ ExistingSBB (t ) , there are relations
priorityx (t) : R α Z
childrenx (t ) : R α P( ExistingSBB( t))
child _ o bjectsx ( t) : R α P(ChildRelationObjects( t))
parentx ( t) : R α P( ExistingSBB(t))
activitiesx (t ) : R α P( ExistingContext(t ))
attachment_ countx ( t) : R α Z
event _ typex ( name, t ) : EventName × R α EventType
describing the priority, children, child relation objects, parent, Activity Contexts18, and event type mapping
for that SBB entity at time t.
{ }
The image of parentx (t ) is the set x ∈ P( ExistingSBB (t )) : x ≤ 1 , i.e. the elements of
P( ExistingSBB(t )) that are sets containing at most one element, and an SBB entity x that is a root SBB
entity for a Service will have parentx ( t ) = {} . (For a time t’ such that x ∉ ExistingSBB(t ' ) , the above rela-
tions are undefined.) We let
16
SBB entities are discussed in Section A.2.5.
17
Convergence names are discussed in Section A.3.2.
18
ExistingContext(t) is defined in Section A.2.7.
Appendix A
SleeSBB= Υ ExistingSBB(t)
t ∈R
be the set of all SBB entities that exist during the lifetime of the SLEE.
A.2.6 Services
Let Service be the set of all Services. A Service v is a 4-tuple,
( v1 , v2 , v3 , v 4 ) ∈ Z × Z × SBBComponent × ChildRelationObject ,
where v1 is the identity of the Service, v 2 is the default priority of the Service, v3 is the root SBB comp o-
nent for the Service, and v4 is the child relation object for the Service. SleeService(t) is a relation which
specifies the set of Services that are known to the SLEE at time t:
SleeService(t ) : R α P (Service)
A.2.7 Activity Contexts

Let ActivityContext be the set of all Activity Contexts. Let ExistingContext(t) be the set of Activity Con-
texts that are said to ‘exist’ at time t. An Activity Context ac is an ordered pair,
( ac1, ac2 ) ∈ Z × Activity,
where ac1 is the identity of the Activity Context and ac 2 is the activity of the Activity Context, together
with relations
attachedac (t ) : R α P( ExistingSBB( t ))
deliveredac (e, t ) : Event × R α P( ExistingSBB( t ))
type _ maskac (sbbe , t ) : ExistingSBB(t ) × R α P ( EventType)
name _ maskac (sbbe , t ) : ExistingSBB( t ) × R α P ( EventName)
where attachedac (t ) is the set of SBB entities that are said to be ‘attached’ to the Activity Context at time t
and deliveredac (e, t ) is the set of SBB entities to which the event e has been delivered at time t.
A.3 Further Properties
A.3.1 Uniqueness of SBB Entities

The identity of an SBB entity is unique:
∀ x, y ∈ SleeSBB, x1 = y1 ⇔ x= y
A.3.2 Convergence names

Only root SBB entities have a convergence name:
∀ t ∈ R , s ∈ RootSBB(t ) ⇔ s 3 = 1
∀ t ∈ R , s ∈ ExistingSBB (t ) − RootSBB( t ) ⇔ s3 = { }
A.3.3 Delivered and attached

∀ t ∈ R, e∈ Event, deliveredac (e, t ) ⊆ attachedac (e, t)

Appendix A
A.3.4 Descendents and ancestors

An SBB entity d ∈ ExistingSBB(t ) is a descendent of a ∈ ExistingSBB(t ) at time t if and only if
∃s1, s2 , . . . , s N ∈ ExistingSBB (t) such that
parents 1 ( t ) = {s 2 }, parents 2 ( t ) = {s 3 }, ..., parents N − 1 (t ) = {s N }
where d = s 1 and a = s N . If d is a descendent of a, then a is an ancestor of d. The set of all descendents of

an SBB entity x at time t is written
descendents x (t ) = {y : y is a descendentof x at time t}
A.3.5 Priority of attached SBB entities with respect to an Activity Context

and event
Let
deliverableac (e, t) : Event × R α P( ExistingSBB(t ))
be the set of SBB entities attached to the Activity Context ac at time t that have the event type of e in the
SBB component’s received event set and have not received or masked the event e, defined as:
deliverableac (e, t) = attachedac( t) − {{x : e2 ∈ type_ maskac ( x, t ) ∨ e2 ∉ ( x2 ) 3} ∪ deliveredac (e, t)}
Let
origin ( x, t ) : SBBEntity × R α P ( ExistingSBB( t ))
be the set consisting of the (unique) ancestor of x which has no parent, defined as:
{x } if parentx (t ) ={ }, otherwise
origin (x , t ) = { {sbbe : x ∈ descendents sbbe (t ) ∧ parentsbbe (t ) = { }}
Let next _ sbbeac ( e, t ) be the set consisting of the SBB entity attached to the Activity Context ac at time t
that will be next to receive the event e.
next _ sbbeac ( e, t ) contains at most one SBB entity,
next _ sbbeac (e, t ) ≤ 1 .
Definition of next _ sbbeac ( e, t ) : If there are no deliverable SBB entities for the event on the Activity Con-
text, then next _ sbbeac ( e, t ) is the empty set:
deliverableac (e, t ) = {} ⇒ next _ sbbeac (e, t ) = {} .
Otherwise, let stack be a sequence of SBB entities.

While
origin( deliverableac (e, t ), t ) − stack ≠ { } ,
add
y = x ∈ origin( deliverabl
min arg
eac (e ,t ) , t ) − stack priorityx (t )
to the end of stack .

While stack ≠ {} and next _ sbbeac ( e, t ) has not been determined:
• Remove the last element, z, from stack;
• If z ∈ deliverableac (e, t ) then next _ sbbeac (e, t ) = {z} ;
• Otherwise, while
Appendix A
childrenz (t ) − stack ≠ {} ,
add
y =z ∈ children
min arg
z (t ) − stack
priorityz (t)
to end of stack .
A.3.6 Attachment count

The attachment count at time t for an SBB entity x is defined as
attachment_ countx (t) = activitiesx (t) + ∑ activitiesy (t )

y ∈ descendents x ( t )
A.3.7 Consistency of child-parent relations

All SBB entities that are in children y(t) must have y as their parent, and vice-versa:
∀ t ∈ R, x, y ∈ ExistingSBB( t ), parentx ( t ) = {y} ⇔ x ∈ childreny (t )
A.3.8 Uniqueness of SBB entities with respect to child relation objects

An SBB entity can only be in one child relation object:
∀ t ∈ R, x, y ∈ ExistingChildObject( t), x2 ∩ y2 = { }
A.3.9 Inclusion of child SBB entities in child relation objects

All SBB entities that are a child of an SBB entity sbbe must belong to a child re lation object for sbbe:
∀ t ∈ R, childrensbbe ( t ) = Υ
cro∈child _ objectssbbe (t )
cro 2
A.3.10 Root SBB entities

Let RootSBB(t) : R α P( ExistingSBB (t)) be the set of ‘root’ SBB entities at time t.
RootSBB( t) ⊆ ExistingSBB(t)
RootSBB(t) can also be characterized as
RootSBB(t ) = origin( ExistingSBB( t ), t ).
A.3.11 Reachability of existing SBB entities fro m a root SBB entity

SBB entities that exist at a given point in time must be root SBB entities or have an ancestor that is a root
SBB entity:
ExistingSBB(t ) = RootSBB(t ) ∪ Υ descendents x (t )

x∈RootSBB(t )
A.4 Event queue

The SLEE event queue Q is modeled as a sequence of events
Q = {e1 , e2 , e3 ,...}, ei ∈ Event
together with the relation
event _ time( e) : Event α R

Appendix A
that associates each event in the queue with a time such that
∀ e i , e j ∈ Q , i < j ⇔ event _ time( ei ) < event _ time (e j ).
A.5 Event routing

This section describes the effect of various SLEE operations on the sets of SBB entities and Activity Con-
texts. For the sake of argument we assume that the preconditions are evaluated at a time t 1 < t op and the
post-conditions at a time t 2 > top that are sufficiently close to the time t op at which the operation occurs
that the operation being described is the only significant event to occur in the interval [ t1 , t2 ] .
The assumed event routing logic is:
forever do
receive event on an Activity Context
while there are eligible SBB entities do
deliver event to next eligible SBB entity
endwhile
if event is end event for the Activity Context

terminate Activity Context
endif
endfor
A.5.1 Attach an SBB entity (sbbe) to an Activity Context (ac)

Pre: none
sbbe ∈ attached a c (t 2 )
ac ∈ activities sbbe (t 2 )
Post: type _ maska c ( sbbe , t 2 ) = ( sbbe 2 ) 4
name _ mask a c (sbbe , t 2 ) = (sbbe 2 ) 5
sbbe ∉ delivered a c (t 2 )
Description: If the SBB entity is already attached to the Activity Context, no action is taken. Other-
wise, the SBB entity is attached to the Activity Context, the Activity Context is added to
the SBB entity’s set of Activity Contexts, the event type mask for the SBB entity with
respect to the Activity Context is set to the corresponding SBB component’s mask-on-
attach event types and the event name mask for the SBB entity with respect to the Activ-
ity Context is set to the corresponding SBB component’s mask-on-attach event names.
If the SBB entity is in the Activity Context’s delivered set, it is removed from this set.
A.5.2 Detach an SBB entity (sbbe) from an Activity Context (ac)

Pre: none
sbbe ∉ attachedac (t 2 )
ac ∉ activitiessbbe ( t 2 )
Pre:
type _ mask ac (sbbe , t 2 ) = { }
name _ mask ac (sbbe , t 2 ) = { }
Description: If the SBB entity is not attached to the Activity Context, no action is taken. Otherwise,
the SBB entity is removed from the Activity Context, the Activity Context is removed
from the SBB entity’s set of Activity Contexts, the event type mask for the SBB entity
with respect to the Activity Context is cleared and the event name mask for the SBB en-
tity with respect to the Activity Context is cleared.

Appendix A
A.5.3 Mask the events ( names ⊆ EventNames ) for an SBB entity (sbbe) on n
Activity Context (ac)
Pre: none
type _ mask ac ( sbbe , t 2 ) = event _ typesbbe ( names)
Post:
name _ mask ac ( sbbe , t 2 ) = names
Description: The event name mask for the SBB entity with respect to the Activity Context is set to
given event names, and the event type mask for the SBB entity with respect to the Ac-
tivity Context is set to the corresponding event types.
A.5.4 Remove an SBB entity (sbbe) from a parent SBB entity (p)
Pre: parentsbbe (t1) = {p}
sbbe ∉ ExistingSBB (t 2 )
ac ∈ activitiessbbe (t 1 ) ⇒ sbbe ∉ attachedac (t 2 )
s ∈ descendentssbbe (t 1 )
Post:
⇒ s ∉ ExistingSBB (t 2 )
∀ s ∈ descendentssbbe (t 1 ),
ac ∈ activitiess (t 1 ) ⇒ s ∉ attachedac (t 2 )
Description: The SBB entity is removed from the set of existing SBB entities, and the SBB entity is
detached from each Activity Context in the SBB entity’s set of Activity Contexts. Each
descendent SBB entity is removed from the set of existing SBB entities, and is detached
from each Activity Context in its set of Activity Contexts.
A.5.5 Create a root SBB entity (sbbe) based on a child relation object (cro)
belonging to a Service
Pre: name is the convergence name for the SBB entity computed by the SLEE
sbbe ∈ ExistingSBB (t 2 )
sbbe ∈ cro 2
sbbe2 = (cro1 ) 2
sbbe3 = {name}
Post:
parentsbbe (t 2 ) = {}
prioritysbbe (t 2 ) = (cro1 ) 1
child _ objectssbbe (t 2 ) = {}
activitiessbbe ( t 2 ) = { }
Description: The SBB entity is added to the set of existing SBB entities and the set of child SBB enti-
ties for the child relation object. The SBB component for the SBB entity is the SBB
component of the child relation for the child relation object. The SBB entity’s parent re-
lation maps to the empty set. The priority of the SBB entity is the priority of the child
relation for the child relation object.
A.5.6 Create a non-root SBB entity (sbbe) based on a child relation object
(cro) belonging to an SBB entity (p)
Pre: none

Appendix A
sbbe ∈ ExistingSBB(t 2 )
sbbe ∈ cro2
sbbe2 = ( cro1 ) 2
sbbe3 = { }
Post:
parentsbbe (t 2 ) = {p}
prioritysbbe (t 2 ) = ( cro1 ) 1
child _ objectssbbe (t 2 ) = {}
activitiessbbe (t 2 ) = {}
Description: The SBB entity is added to the set of existing SBB entities and the set of child SBB enti-
ties for the child relation object. The SBB component for the SBB entity is the SBB
component of the child relation for the child relation object. The SBB entity’s parent re-
lation maps to the SBB entity that the child relation object belongs to. The priority of the
SBB entity is the priority of the child relation for the child relation object.
A.5.7 Receipt of event (e) on an Activity Context (ac)

Pre: names is a set of convergence names computed by the SLEE.
deliveredac ( t 2 ) = { }
∀ svc ∈ SleeServices(t1 ) : e2 ∈ ( svc3 ) 2
∃ s ∈ ExistingSBB(t 2 ) :
s3 ∈ names( e, ac )
e3 ∈ activitiess (t 2 )
s ∈ attachede3 ( t 2 )
Post: s ∉ ExistingSBB (t1 ) ⇒
s ∈ ( svc4 ) 2
s 2 = (( svc 4 )1 ) 2
parents ( t 2 ) = { }
prioritys ( t 2 ) = (( svc 4 )1 )1
child _ objectss ( t 2 ) = { }
activitiess (t 2 ) = {ac }
Description: After receipt of the event, each Service for which the event is an initial event has a root
SBB entity instantiated. If the SBB entity was created in response to receipt of the event,
its attributes are set to the default values.
A.5.8 Delivery of event (e) on an Activity Context (ac)

Pre: deliveredac( e, t1 ) ≠ attachedac ( t1 )
next _ sbbeac ( e, t1 ) ∈ attachedac (t 2 ) ∀ t ∈ [t 1 , t 2 ]

Post:
⇔ next _ sbbeac (e, t1 ) ∈ deliveredac ( e, t 2 )
Description: The event is delivered to the SBB entity with the highest priority (as defined in Section
A.3.5). After delivery, the SBB entity (if it remained attached to the Activity Context,
i.e. did not detach and re-attach) is in the delivered set for the Activity Context with re-
spect to the event.

Appendix A
A.5.9 Termination of an Activity Context (ac)

Pre: none
attachedac (t 2 ) = {}
Post:
s ∈ ExistingSBB(t 2 ) ⇒ ac ∉ activitiess (t 2 )
Description: All SBB entities are detached from the Activity Context. After the termination, no exist-
ing SBB entities have the Activity Context in their activities set.
A.5.10 On completion of event routing for an event (e)

Pre: none
Post: s ∈ RootSBB(t 2 ) ⇒ attachment_ counts (t 2 ) > 0
Description: After all eligible SBB entities have received the event, no root SBB entities have an
attachment count of zero.

Appendix B
Event Router Pseudo Code
Appendix B Event Router Pseudo Code

The following pseudo code illustrates the desired behavior of the SLEE event router and the methods that
interact with the event router. The main goal is to reduce ambiguities that may lead to SLEE implementa-
tions that do not implement the specified behavior.
The SLEE vendor is not required to translate the pseudo code directly into imple mentation code. The SLEE
vendor need not follow the same control flow and structure illustrated by the pseudo code, but the SLEE
implementation must implement the desired behavior.
Many of the methods illustrated in this appendix have transactional semantics described in Chapter 9. The
pseudo code for these methods does not include the necessary code to implement the transactional seman-
tics specified in Chapter 9. The pseudo code in this section also does not show SBB object life cycle
method invocations, automatic event subscription, and exception handling.
B.1 Definitions
// Conventions:
// XXX is a set.
// XXX[y] is a member of set XXX.
// XXX[y].ZZZ is an attribute of XXX[y].
// EO[e] is an event object known to the SLEE.

// ET[t] is an event type known to the SLEE.
// SVC[v] is a Service.
// A Service has a default event delivery priority and a root SBB.
// SVC[v].PRIORITY is the default event delivery priority of the Service.
// SVC[v].SBB is the root SBB of the Service.
// SVC[v].CHILDOBJ is the set of the child relation object of the Service.
// This child relation object contains the root SBB entities that have
// been created for this Service.
// SBB[b] is an SBB component.

// SBB[b].CHILD is the set of child relations of the SBB.
// SBB[b].CHILD[c] is a child relation of the SBB.
// SBB[b].CHILD[c].PRIORITY is the default event delivery priority of the child relation.
// SBB[b].CHILD[c].SBB is the child SBB of the child relation.
// SBB[b].IET is the set of initial event types of the SBB.
// SBB[b].RET is the set of received event types of the SBB.
// SBB[b].MOAET is the set of received event types of the SBB whose mask-on-attach
// attribute is set to true.
// SBB[b].MOAEN is the set of event names of the received event types of the SBB
// whose mask on attach attribute is set to true.
// There is a one-to-one mapping between elements of SBB[b].MOAET and the elements
// of SBB[b].MOAEN, i.e. SBB[b].MOAET[x] maps to SBB[b].MOAEN[x] and vice versa.
// SBB[b].IET is subset of SBB[b].RET

// SBB[b].MOAET is subset of SBB[b].RET
// SBB[0] is reserved to represent the SLEE as the logical parent of all root SBBs.
// This means:
// SBB[0].CHILD[v].PRIORITY is always the same as SVC[v].PRIORITY
// SBB[0].CHILD[v].SBB is always the same as SVC[v].SBB
// SBBE[b] is an SBB entity.

// SBBE[b].SBB is the SBB component of the SBB entity.
// SBBE[b].PARENT is the parent SBB entity of the SBB entity.
// SBBE[b].ROOT is the root SBB entity of the SBB entity’s SBB entity tree
// SBBE[b].PRIORITY is the event delivery priority of the SBB entity.
// SBBE[b].CONVNAME is the convergence name of the SBB entity if it is a root SBB entity.
// SBBE[b].CHILDOBJ is the set of child relation objects of the SBB entity
// SBBE[b].CHILDOBJ[c] is a child relation object of the SBB entity.
// SBBE[b].CHILDOBJ[c].CHILD is the child relation of the child relation object.
// SBBE[b].CHILDOBJ[c].SBBE is the set of child SBB entities of a child relation object.

Appendix B
// SBBE[b].CHILDOBJ[c].SBBE[f] is a child SBB entity of a child relation object.
// SBBE[b].ACOUNT is the attachment count of the SBB entity.
// SBBE[b].AC is the set of Activity Contexts that the SBB entity is attached to.
// SBBE[b].AC[a] is an Activity Context that the SBB entity is attached to.
// SBBE[0] is the SLEE as the logical parent SBB entity of all root SBB entities.
// Relationship between SVC[v].CHILDOBJ and SBBE[0].CHILDOBJ[v].

// Logically, each Service is represented by a child relation object
// in the SLEE SBB entity, i.e. SBBE[0].
// SVC[v].CHILDOBJ is the same as SBBE[0].CHILDOBJ[v].
// AC[a] is an Activity Context.

// AC[a].SBBE is the set of SBB entities attached to the Activity Context.
// AC[a].SBBE[b] is an SBB entity attached to the Activity Context.
// AC[a].DELIVERED is the set of SBB entities that an event has been delivered to.
// AC[a].DELIVERED[a] is an SBB entity that an event has been delivered to.
// A[a] is the Activity object of Activity Context AC[a] and vice versa,
// i.e. there is a one-to-one mapping between Activity Contexts and
// Activity objects.
// Each SBB entity attached to an Activity Context has its own event name mask
// and event type mask.
// ENM(SBBE[b],AC[a]) is the set of received event names of SBBE[b].SBB that
// SBBE[b] would like to mask from AC[a].
// ETM(SBBE[b],AC[a]) is the set of received event types of SBBE[b].SBB that
// SBBE[b] would like to mask from AC[a].
// Q is the SLEE’s event queue.

// Q[q] represent an event in the event queue.
// Q[q].ET is the event type of the event.
// Q[q].EO is the event object of the event.
// Q[q].AC is the Activity Context on which the event was fired.
// Q[q].ADDR is the address on which the event was fired.
B.2 ActivityContextInterface interface attach method pseudo code

SUBROUTINE ac.attach(sbbe)
// ac is member of AC.
// sbbe is member of SBBE.
if (ac is not a member of sbbe.AC) then
add sbbe to ac.SBBE
add ac to sbbe.AC
ETM(sbbe,ac) = (sbbe.SBB).MOAET
ENM(sbbe,ac) = (sbbe.SBB).MOAEN
// If there is an event being routed on this Activity Context, then
// the SLEE should deliver this event to this SBB entity.
if sbbe in ac.DELIVERED then
remove sbbe from ac.DELIVERED
endif
// Iterate through the SBB entity and the ancestors of the SBB entity.
do
// Increment their attachment count.
sbbe.ACOUNT = sbbe.ACOUNT + 1
sbbe = sbbe.PARENT
while sbbe is not SBBE[0]
endif
END SUBROUTINE
B.3 ActivityContextInterface interface detach method pseudo code

SUBROUTINE ac.detach(sbbe)
// ac is a member of AC.
// sbbe is a member of SBBE.
if (ac is a member of sbbe.AC) then
remove sbbe from ac.SBBE
remove ac from sbbe.AC

Appendix B
ETM(sbbe,ac) = {}
ENM(sbbe,ac) = {}
// Iterate through the SBB entity and the ancestors of the SBB entity.
do
// Decrement attachment count.
sbbe.ACOUNT = sbbe.ACOUNT – 1
sbbe = sbbe.PARENT
while sbbe is not SBBE[0]
endif
END SUBROUTINE
B.4 SbbContext interface getActivities method pseudo code

SUBROUTINE sbbe.getActivities()
return sbbe.AC;
END SUBROUTINE
B.5 SbbContext interface getEventMask method pseudo code

SUBROUTINE sbbe.getEventMask(ac)
return ENM(sbbe,ac);
END SUBROUTINE
B.6 SbbContext interface maskEvent method pseudo code

SUBROUTINE sbbe.maskEvent(eventNames[], ac)
// eventNames is an array of event names
// Create a new set for event types.

met = {}
for each eventName in eventNames[] do
et = sbbe.mapEventNameToEventType(eventName)
add et to met
endfor
ETM(sbbe,ac) = met
ENM(sbbe,ac) = eventNames
END SUBROUTINE
B.7 SbbLocalObject interface getSbbPriority method pseudo code

SUBROUTINE sbbe.getPriority()
return sbbe.PRIORITY;
END SUBROUTINE
B.8 SbbLocalObject interface setSbbPriority method pseudo code

SUBROUTINE sbbe.setPriority(priority)
sbbe.PRIORITY = priority;
END SUBROUTINE
B.9 SbbLocalObject interface remove method pseudo code

SUBROUTINE sbbe.removeInternal(sbbeParentChildRelationObj)
// sbbeParentChildRelationObj is a member of the parent SBB entity’s set of
// child relation objects.
for each childRelationObj in sbbe.CHILDOBJ do
for each sbbeChild in childRelationObj do

Appendix B
sbbeChild.removeInternal(childRelationObj)
endfor
endfor
…
invoke sbbRemove life cycle method on sbbe
…
for each ac in sbbe.AC do
ac.detach(sbbe)
endfor
sbbe.PARENT = null
remove sbbe from sbbeParentChildRelationObj
…
// sbbe can now be reclaimed.
ENDSUBROUTINE
SUBROUTINE sbbe.remove()
for each childRelationObj in sbbe.PARENT.CHILDOBJ do
if sbbe is a member of childRelationObj.SBBE then
sbbe.removeInternal(childRelationObj)
break
endif
endfor
END SUBROUTINE
B.10 ChildRelation interface create method pseudo code

SUBROUTINE childRelationObj.create()
// childRelationObj is a child relation object of the parent SBB
// entity, i.e. it is a member of sbbeParent.CHILDOBJ where
// sbbeParent is a member of SBBE and is the parent SBB entity that the
// child relation object belongs to.
// childRelationObj.CHILD is the child relation of the child relation object,
// i.e. it is a sbbeParent.CHILDOBJ[c].CHILD and is the
// same as (sbbeParent.SBB).CHILD[c].
sbbe = new instance of (childRelationObj.CHILD).SBB
sbbe.SBB = (childRelationObj.CHILD).SBB
sbbe.PARENT = sbbeParent
if sbbeParent is SBBE[0] then
sbbe.ROOT = sbbe
else
sbbe.ROOT = sbbeParent.ROOT
endif
sbbe.PRIORITY = (childRelationObj.CHILD).PRIORITY
add sbbe to childRelationObj.SBBE
return sbbe
ENDSUBROUTINE
B.11 SBB abstract class fire event method pseudo code

SUBROUTINE sbbe.fire<EventName>(eo, ac, address)
// eo is a member of EO.
// address is the default address of the event being fired
// et is the event type of event being fired, it is typically embedded

// in the SLEE generated implementation of this method.
et = sbbe.mapEventNameToEventType(EventName)
add (et, eo, ac, address) to the tail of the event queue Q
END SUBROUTINE
B.12 Event router pseudo code

The following pseudo code illustrates the desired behavior of the SLEE event router.
SUBROUTINE priorityOfSBBE(sbbe)
stack = create empty new stack
Appendix B
while sbbe is not SBBE[0] do
stack.push(sbbe) // push SBBE
sbbe = sbbe.PARENT
endwhile
return stack
ENDSUBROUTINE
SUBROUTINE higherPrioritySBBE(sbbe1, sbbe2)

// sbbe1 and sbbe2 are members of SBBE.
stack1 = priorityOfSBBE(sbbe1);
stack2 = priorityOfSBBE(sbbe2);
for ever do
sbbe1a = stack1.pop()
sbbe2a = stack2.pop()
if sbbe1a.isIdentical(sbbe2a) then
// sbb entities have same ancestor
if stack1.isEmpty() then
// sbbe1 is an ancestor of sbbe2
return sbbe1
else if stack2.isEmpty() then
// sbbe2 is an ancestor of sbbe1
return sbbe2
else
// do nothing, just keep going down hierarchy
endif
else
// sbb entities have different ancestors, so choose based
// on higher priority ancestor
if sbbe1a.PRIORITY > sbbe2a.PRIORITY then
return sbbe1
else if sbbe1a.PRIORITY < sbbe2a.PRIORITY then
return sbbe2
else if identity(sbbe1a) > identity(sbbe2a) then
return sbbe1
else
return sbbe2
endif
endif
endfor
ENDSUBROUTINE
SUBROUTINE processInitialEvents(svc, q)
// svc is a member of SVC.
// q is a member of Q.
// Compute the one or more convergence names according to the initial-event-select

// and/or the initial-event-selector-method-name elements of the root SBB of the
// Service.
// names is an array of convergence names
names[] = computeConvergenceNames(…);
// If initial event selector method indicates this is not an initial event
// for this Service, then return.
if names[] is null then
return
endif
// Iterate through each convergence name

for each name in names[] do
// Determine if there is a root SBB entity of this Service with
// this computed convergence name.
found = false
for sbbe in (svc.CHILDOBJ).SBBE do
if sbbe.CONVNAME == name then
found = true
break
endif
endfor
if not found then
// No root SBB entity with the convergence name exist.

Appendix B
// Create root SBB entity as child of SLEE
sbbe = (svc.CHILDOBJ).create()
// If create fails, then process the next convergence name,
// don’t associate convergence name and don’t attach.
if create fails then
continue
endif
// Remember the convergence name of this child SBB entity.
sbbe.CONVNAME = name
endif
// Attach either found or new SBB entity to the Activity Context.
(q.AC).attach(sbbe);
endfor
END SUBROUTINE
SUBROUTINE routeEvent(q)
// q is a member of Q
// Iterate through each Service that has the event type as an initial event type.
for each svc in SVC do
if q.ET is a member of (svc.SBB).IET then
processInitialEvents(svc,q);
endif
endfor
// Deliver event to SBB entities attached to the Activity Context
(q.AC).DELIVERED = {}
for ever do
// Find the highest priority SBB entity attached to the
// Activity Context that the event has not been delivered to.
highestPrioritySBBE = null;
for each sbbe in (q.AC).SBBE do
if q.ET is a member of sbbe.SBB.RET and
sbbe is not a member of (q.AC).DELIVERED then
if highestPrioritySBBE == null then
highestPrioritySBBE = sbbe
else
highestPrioritySBBE =
higherPrioritySBBE(sbbe,
highestPrioritySBBE)
endif
endif
endif
// If no such SBB entity is found, then event routing for this event
// is complete.
if highestPrioritySBBE is null then
break;
add highestPrioritySBBE to (q.AC).DELIVERED
// Check event mask and invoke appropriate event handler method
if q.ET is not a member ETM(highestPrioritySBBE,q.AC) then
invoke event handler method for q.ET on an SBB object
that represents highestPrioritySBBE with arguments
(q.EO, q.AC)
// If event is Activity End Event, then detach the SBB entity
// from the Activity Context.
if q.ET is Activity Event Event then
(q.AC).detach(sbbe)
endif
// If root SBB entity of SBB entity’s SBB entity tree
// has attachment count of 0, then delete the SBB entity tree
if (sbbe.ROOT).ACOUNT is 0 then
remove sbbe.ROOT
endif
endif
endfor
// If event is Activity End Event, then detach all remaining SBB entities from the
// Activity Context.
if q.ET is Activity Event Event then
for each sbbe in (q.AC).SBBE do
(q.AC).detach(sbbe)

Appendix B
// If root SBB entity of SBB entity’s SBB entity tree
// has attachment count of 0, then delete the SBB entity tree
if (sbbe.ROOT).ACOUNT is 0 then
remove sbbe.ROOT
endif
endfor
endif
END SUBROUTINE
SUBROUTINE eventRouterThread()
while (…) do
q = item removed from the head of the event queue Q
routeEvent(q);
endwhile
END SUBROUTINE

Appendix C
JCC Resource Adaptor Type
Appendix C JCC Resource Adaptor Type

This appendix describes a recommended adaptation of a JCC v1.1 resource to the SLEE.
C.1 Resour ce adaptor type identifier

The resource adaptor type name is “JCC”. The resource adaptor type vendor is “javax.csapi.cc.jcc”. The
resource adaptor type version is “1.1”.
C.2 Activity objects

The Activity objects of a JCC resource are the JccConnection objects and JccCall objects.
C.3 Events
The following table lists the events emitted by a JCC resource and its Activity objects.
Event Activity Object
(JccEvents with different JCC event IDs are different
event types) JccConnection JccCall Remarks
JCC CALL EVENTS
CALL_ACTIVE X
CALL_CREATED X
CALL_EVENT_TRANSMISSION_ENDED X 1.
CALL_INVALID X
CALL_SUPERVISE_END X
CALL_SUPERVISE_START X
JCC CONNECTION EVENTS
CONNECTION_ALERTING X
CONNECTION_CONNECTED X
CONNECTION_CREATED X
CONNECTION_DISCONNECTED X 2.
CONNECTION_FAILED X
CONNECTION_ADDRESS_ANALYZE X
CONNECTION_ADDRESS_COLLECT X
CONNECTION_AUTHORIZE_CALL_ATTEMPT X
CONNECTION_CALL_DELIVERY X
CONNECTION_MID_CALL X
1. After this event there are no more events on the JccCall object. The JCC resource adaptor
entity responsible for JccCall object should indicate to the SLEE that this Activity object has
ended. This event should only be delivered to the SLEE after the JCC resource adaptor entity
has indicated to the SLEE that all the JccConnection Activity objects of the JccCall ob-
ject have also ended.
2. After this event there are no more events on the JccConnection object. The JCC resource
adaptor entity responsible for the JccConnection object should indicate to the SLEE that
this Activity object has ended.

Appendix C
JCC Resource Adaptor Type
C.3.1 Event types

The event type name of an event is the fully qualified name of the constant value field that defines the JCC
event ID for the event. For example, the event type name of a JccConnectionEvent with a JCC event
ID of CONNECTION_ALERTING is
“javax.csapi.cc.jcc.JccConnectionEvent.CONNECTION_ALERTING”. The event type vendor and event
type version must be “javax.csapi.cc.jcc” and “1.1”, respectively.
C.3.2 Event classes

The event classes for each of these events are defined by JCC.
• The event class of a CALL_<XXX> event is the javax.csapi.cc.jcc.JccCallEvent in-
terface.
• The event class of a CONNECTION_ <XXX> event is the javax.csapi.cc.jcc.JccCon-
nectionEvent interface.
C.4 Activity Context Interface Factory interface

The interface of the JCC resource adaptor type specific Activity Context Interface Factory should be as
follows:
…
import javax.csapi.cc.jcc.JccCall;
import javax.csapi.cc.jcc.JccConnection;
…
public interface JccActivityContextInterfaceFactory {
getActivityContextInterface(JccCall call)
FactoryException;
getActivityContextInterface(JccConnection connection)
FactoryException;
}
C.5 Resource adaptor object

The resource adaptor object that is bound to an SBB’s component environment when the SBB uses a re-
source-adaptor-entity-binding deployment descriptor element to reference a JCC resource is a
JccProvider object, i.e. the resource-adaptor-interface-name element contains
javax.csapi.cc.jcc.JccProvider.
C.6 Restrictions
The following restrictions apply:
• Only the SLEE can add itself as a listener. The JCC resource or its resource adaptor should not al-
low any other objects to add themselves as listeners. An attempt to do so should be rejected by
throwing a SecurityException.

Appendix D
JAIN SIP Resource Adaptor Type
Appendix D JAIN SIP Resource Adaptor Type

This appendix describes a recommended adaptation of a JAIN SIP v1.1 resource to the SLEE. JAIN SIP is
a Java representation of the Session Initiation Protocol as defined by the IETF in RFC 3261 that also sup-
ports SIP extensions, RFC 2976, RFC 3262, RFC 3265, RFC 3311, RFC 3326 and RFC 3248.
D.1 Resource Adaptor type identifier

The resource adaptor type name is “JAIN SIP”. The resource adaptor type vendor is “javax.sip”. The re -
source adaptor type version is “1.1”.
D.2 Activity objects

The Activity objects of a JAIN SIP resource are ClientTransaction and ServerTransaction
objects, i.e. objects that implement the javax. sip.ClientTransaction and javax.sip.Ser-
verTransaction interface. A ClientTransaction is a local initiated Activity and a Server-
Transaction is a remotely initiated Activity.
New client Activity objects are created by calling the SipProvider.getNewClientTransaction
method and new server Activity objects are created by SipProvider.getNewServerTransaction
on the javax.sip.SipProvider.
D.3 Events
The following table lists the events emitted by a JAIN SIP resource and its Activity objects. The event
definitions can be found in the RequestEvent and ResponseEvent interfaces in the javax.sip
package.
Events Activity Object
(SipEvents consist of messages which are either Server Client
responses or requests) Transaction Transaction Remarks
JAIN SIP Request Events
RequestEvent.Request.INVITE X 1.
RequestEvent.Request.ACK X
RequestEvent.Request.CANCEL X 2.
RequestEvent.Request.OPTIONS X
RequestEvent.Request.REGISTER X
RequestEvent.Request.BYE X 2.
RequestEvent.Request.PRACK X
RequestEvent.Request.NOTIFY X
RequestEvent.Request.SUBSCRIBE X
RequestEvent.Request.INFO X
RequestEvent.Request.MESSAGE X
RequestEvent.Request.UPDATE X
JAIN SIP Response Events
ResponseEvent.Response.INFORMATIONAL (1xx) X
ResponseEvent.Response.SUCCESS (2xx) X
ResponseEvent.Response.REDIRECTION (3xx) X
ResponseEvent.Response.CLIENT_ERROR (4xx) X

Appendix D
ResponseEvent.Response.SERVER_ERROR (5xx) X
ResponseEvent.Response.GLOBAL_FAILURE (6xx) X
JAIN SIP Transaction Management Events
TimeoutEvent.TRANSACTION_TIMEOUT X X
TimeoutEvent.TRANSACTION_EXPIRED X X 3.
1. This event may or may not represent a new dialog in the underlying JAIN SIP resource.
2. This event signals that an application wants to end the dialog in the underlying resource adaptor.
3. This event signals that the underlying transaction failed due to receiving no response to a re-
quest before the maximum number of retransmissions of that request. The JAIN SIP resource
adapter entity that represents the JAIN SIP resource should signal to the SLEE that the Activity
object for this call has ended.
D.3.1 Event types

The event type name of an event is the fully qualified name of the constant value field that defines the
event. For example, the event type of a “Request” message of type “INVITE” is “javax.sip.RequestEvent.-
Request.INVITE”.
The event type vendor and event type version are “javax.sip” and “1.1”, respectively.
D.3.2 Event classes

JAIN SIP defines a event class for all the events. The event classes defined by JAIN SIP are javax.si-
p.TimeoutEvent, javax.sip.ResponseEvent and javax.sip.RequestEvent.
D.4 Activity Context Interface Factory interface

The interface of the JAIN SIP resource adaptor type specific Activity Context Interface Factory should be
as fo llows:
…
…
public interface SipActivityContextInterfaceFactory {
getActivityContextInterface(ClientTransaction clientTransaction)
FactoryException;
getActivityContextInterface(ServerTransaction serverTransaction)
FactoryException;
D.5 Resource adaptor object

JAIN SIP applications require four objects for creating and sending messages. These are SIP stack vendor's
implementations of the javax.sip.SipProvider, javax.sip.address.AddressFactory,
javax.sip.message.MessageFactory and javax.sip.header.HeaderFactory inter-
faces. An SBB must be able to obtain these objects from its component environment. However this specifi-

Appendix D
cation only allows an RA type to define a single resource-adaptor-interface-name element. A
future release of this specification may remove this limitation. In the meantime, it is recommended that
implementors of JAIN SIP resource adaptors provide a single wrapper interface that allows an SBB to re-
trieve the above four objects. An example of how this interface may look is shown below:
package javax.slee.sip;
import javax.sip.SipProvider;
import javax.sip.address.AddressFactory;
import javax.sip.header.HeaderFactory;
import javax.sip.message.MessageFactory;
public interface JainSipResourceAdaptorSbbInterface {

public SipProvider getSipProvider();
public AddressFactory getAddressFactory();
public HeaderFactory getHeaderFactory();
public MessageFactory getMessageFactory();
}
This object can be made available using the RA type's resource-adaptor-interface-name ele -
ment, and bound into the SBB's component environment using the resource-adaptor-entity-
binding element in the SBB deployment descriptor.
D.6 Restrictions
• Only the SLEE can add itself as a listener. The JAIN SIP resource or its resource adaptor should
not allow any other objects to add themselves as listeners. An attempt to do so may be rejected by
throwing a SecurityException.

Appendix E
JAIN TCAP Resource Adaptor Type
Appendix E JAIN TCAP Resource Adaptor Type

This appendix describes a recommended adaptation of a JAIN TCAP resource to the SLEE. JAIN TCAP is
a Java representation of the Transaction Capabilities Application Part layer of a Signaling Systems 7 (SS7)
protocol stack. The JAIN TCAP specification can map to the ITU 1993, ITU 1997, ANSI 1992 and ANSI
1996 versions of the TCAP protocol.
E.1 Resource adaptor type identifier

The resource adaptor type name is “JAIN TCAP”. The resource adaptor type vendor is “jain.protocol.ss7.t -
cap”. The resource adaptor type version is “1.1”.
E.2 Activity objects

The Activity objects of a JAIN TCAP resource are Java.lang.Integer objects that encapsulate inte-
ger dialogueIds. Allocation of dialogueId’s in the TCAP stack is often the responsibility of the TCAP
stack, however JAIN TCAP provides the ability to request a new dialogueId from the TCAP stack with the
SipProvider.getNewDialogueId method, which in turn would map to a new Activity in the re-
source adapter.
Sending an AbortReqEvent and EndReqEvent message on the SipProvider terminate the local
Activity object, i.e. AbortIndEvent and EndIndEvent terminate the remote Activity object,
the resource adapter must terminate its local representation of the Activity object upon the local users
decision to send the Request messages.
E.3 Events
The following table lists the events emitted by a JAIN TCAP resource and its Activity objects.
java.lang.Integer
Events containing dialogueId Remarks
DIALOGUE EVENTS
BeginIndEvent X 1.
ContinueIndEvent X
EndIndEvent X 2.
NoticeIndEvent X
ProviderAbortIndEvent X 3.
UnidirectionalIndEvent X 4.
UserAbortIndEvent X 5.
COMPONENT EVENTS
InvokeIndEvent X
ResultIndEvent X
ErrorIndEvent X
RejectIndEvent X
LocalCancelIndEvent X
1. This event represents a new dialogue in the underlying JAIN TCAP resource (or Activity object
in the JAIN TCAP resource adaptor entity) initiated by the remote user, which is represented as
a new Activity Context within the SLEE.

Appendix E
2. This event signals that there are no more events on the dialogue identified by the dialogueId
attribute of the event object. An EndReqEvent event alerts the JAIN TCAP resource that the
dialogue (or Activity object) has ended. The resource adaptor entity that represents the JAIN
TCAP resource should signal to the SLEE that the Activity object has ended on receipt of an
EndIndEvent event.
3. This event signals that the underlying JAIN TCAP resource has abruptly ended the specified
dialogue. The dialogue has been terminated by the JainTcapProvider in reaction to a
transaction abort by the transaction sub-layer. Any pending components on the Activity object
are not transmitted. The resource adaptor entity that represents the JAIN TCAP resource should
signal to the SLEE that the Activity object has ended on receipt of a ProviderAbortIndE-
vent event.
4. The UnidirectionalIndEvent event is used by the JAIN TCAP resource as a means to

pass components to an SBB when no reply is expected. This primitive is used when there is no
need to establish a dialogue with another TC User, however an Activity object should be cre-
ated in order to route the primitives in the SLEE.
5. This event signals that the remote TCAP user has abruptly ended the specified dialogue. The
resource adaptor entity that represents the JAIN TCAP resource should signal to the SLEE that
the Activity object has ended on receipt of an AbortIndEvent event.
E.3.1 Event types

The event type name of an event type is the fully qualified name of the class for the event type. For exa m-
ple, the event type name of BeginIndEvent is “jain.protocol.ss7.tcap.dialogue.BeginIndEvent”.
The event type vendor and event type version are “jain.protocol.ss7.tcap” and “1.1”, respectively.
E.3.2 Event classes

The event classes for each of these event types are defined by JAIN TCAP.
• The event classes of dialogue primitives all extend the jain.protocol.ss7.tcap.Dia-
logueIndEvent abstract class.
• The event classes of component primitives all extend the jain.protocol.ss7.tcap.Com-
ponentIndEvent abstract class.
E.4 Activity Context Interface Factory interface

The interface of the JAIN TCAP resource adaptor type specific Activity Context Interface Factory should
be as follows:
…
…
public interface JainTcapActivityContextInterfaceFactory {
getActivityContextInterface(Integer dialogueId)
FactoryException;
}

Appendix E
E.5 Resource adaptor object

The resource adaptor object that is bound to an SBB’s component environment when the SBB uses a re-
source-adaptor-entity-binding deployment descriptor element to reference a JAIN TCAP re-
source is a JainTcapProvider object, i.e. the resource-adaptor-interface-name element
contains jain.protocol.ss7.tcap.JainTcapProvider.
E.6 Restrictions
• Only the SLEE can add itself as a listener. The JAIN TCAP resource or its resource adaptor
should not allow any other objects to add themselves as listeners. An attempt to do so may be re -
jected by thro wing a SecurityException.

Appendix F
Integration with EJB applications
Appendix F Integration with EJB applications

This appendix specifies how SBBs may invoke EJBs and how EJBs may pass events to the SLEE.
F.1 Invoking an EJB

From the EJB specification perspective, an SBB is a remote client (see Sections 6.1 and 9.2 of the “Enter-
prise JavaBeans 2.0, Final Release” specification).
An SBB may invoke an EJB through the use of the EJB’s home interface. The home interface reference is
gained through the SBB’s component environment.
The location of a home interface in the SBB’s component environment and the type of the home interface
are specified using the ejb-ref element in the SBB’s deployment descriptor. For more information see
Section 3.1.8.
EJB components have transactional semantics. For more information regarding possible transaction scenar-
ios, see Section 9.9.
F.1.1 Example code

This following example shows how an SBB may obtain a reference to the home interface of an EJB com-
ponent.
…
// obtain the SBB component environment naming context.
…
// get reference to the home object
Object homeRef = myEnv.lookup("location/of/home/interface");
ParticularEjbHome home = (ParticularEjbHome)
PortableRemoteObject.narrow(homeRef, ParticularEjbHome.class);
…
// invoke methods on the home object
try{
home.remove(somePrimaryKeyObject);
} catch ( … )
…
}
F.2 Passing an event to SLEE

An EJB component may pass an event to the SLEE in order to drive application logic contained within the
SLEE. This section describes the application visible API that can be used to send events to the SLEE. An
EJB developer is e xpected to understand the EJB model for using external resources in order to use this
API. For more information see the EJB 2.0 specification and the JCA 1.0 specification.
The EJB developer may use the following APIs to pass events to SLEE.
package javax.slee.connection;
public interface ExternalActivityHandle extends java.io.Serializable {

public boolean equals(Object other);
}
public interface SleeConnection{

public ExternalActivityHandle createActivityHandle();
public void fireEvent(Object event, javax.slee.EventTypeID eventType, ExternalAc-
tivityHandle activityHandle, javax.slee.Address address);
public javax.slee.EventTyeID getEventTypeID(String name, String vendor, String
version);
public void close();
}

Appendix F
public interface SleeConnectionFactory {

public SleeConnection getConnection();
}
The connection factory instance gained by an EJB component will implement the javax.slee.con-
nection.SleeConnectionFactory interface. This interface allows EJB components to obtain
javax.slee.connection.SleeConnection instances representing connections to an external
SLEE as needed via the SleeConnectionFactory.getConnection method.
A SleeConnection instance allows an EJB component to create external activity handles, retrieve
SLEE event type identifiers, and fire events to the SLEE. Each SleeConnection remains open until
explicitly closed via the SleeConnection.close method.
To ensure that the SLEE can correctly identify and deserialize events sent via the SleeConnection in-
terface, each event fired has an associated event type obtained via the SleeConnec-
tion.getEventTypeID method that identifies the event type by name, vendor, and version. The class
of the event type specified should be compatible with the actual type of the event object fired.
Events fired via the SleeConnection interface are delivered to Null Activities. The creation of these
activities is managed by the SLEE in response to external event firing, and they are subject to the normal
null activity garbage-collection rules.
EJB components create one or more external activity handles via the SleeConnec-
tion.createActivityHandle method. The ExternalActivityHandle interface represents
these handles. External activity handles can be used to fire events via the SleeConnection that created
them; the visibility of the created handles to other SleeConnection instances is implementation-
defined.
The mapping between external activity handles and null activities is implementation-specific, but must
have the following characteristics:
• Firing an event with an external activity handle that is not mapped to an existing null activity will
cause the creation of a new null activity associated with the external activity handle.
• Subsequent events with the same handle are delivered to the same activity, while the activity exists.
• When a null activity ends, any association with an external activity handle is cleared. If a subsequent
event is fired using this handle, it is treated as though there is no mapping (i.e. a new activity will be
created).
The SleeConnection.createActivityHandle, SleeConnection.getEventTypeID, and
SleeConnection.close methods do not have transactional behavior.
The SleeConnection.fireEvent method has required transactional behavior. If a transaction is in
progress when this method is called, processing of the fired event is deferred until this transaction is known
to have committed. Failure to fire the event is not required to cause rollback of the enclosing transaction.
Within a transaction, delivery order of fired events is preserved.
A successful commit of a transaction that fires events does not guarantee that the fired events will be proc-
essed by the SLEE. EJB and SBB developers should accommodate the possibility of event loss (for exa m-
ple, via timers).
A SLEE implementation is not required to provide an implementation of these interfaces.
F.2.1 Example code

The following example shows how an EJB component may fire events to an external SLEE.
// Obtain a reference to the connection factory from JNDI
InitialContext ctx = new InitialContext();
SleeConnectionFactory factory =
(SleeConnectionFactory)ctx.lookup("java:comp/env/slee/MySleeConnectionFactory");

Appendix F
// Obtain a connection to the SLEE from the factory

SleeConnection connection = factory.getConnection();
try {
// Locate the event types for two different events
EventTypeID eventTypeOne = connection.getEventTypeID("MyEventOne","MyVendor","0.1");
EventTypeID eventTypeTwo = connection.getEventTypeID("MyEventTwo","MyVendor","0.1");
MyEventOne eventOne = ...;

MyEventTwo eventTwo = ...;
// Fire two events on a newly created null activity

ExternalActivityHandle handle = connection.createActivityHandle();
connection.fireEvent(eventOne, eventTypeOne, handle, null);
connection.fireEvent(eventTwo, eventTypeTwo, handle, null);
} finally {
// Done with the connection. Close it.
connection.close();
}

Appendix G
Frequently Asked Questions
Appendix G Frequently Asked Questions

G.1 Persistence
The SLEE specification uses the term “persistent” to describe state that can survive certain documented
failures. Examples of persistent state include CMP fields of SBB entities, Activity Contexts (attached SBB
entities and attributes), SLEE defined Activity objects, Profile CMP fields, and Timers.
However, the SLEE does not define what “persistence” means. This is intentional to allow SLEE vendors
to provide different levels of persistence. Individual SLEEs can be optimized or customized to the require-
ments of their applications or operational environments. In some cases, a single SLEE may provide diffe r-
ent persistence levels to support different application or operational requirements.
In general, a better or higher persistence level can maintain persistent state across more types of failures but
has poorer performance because of higher processing overhead and higher transactional latencies.
For example, one level of persistence may store persistent state in disk based stable storage. Persistent state
is maintained across complete failures of the SLEE, e.g. all nodes of the SLEE cluster fails. This level of
persistence is typical in commercial transaction processing systems. However, it may not be appropriate for
real-time communications applications because of relatively long disk access latencies to commit persistent
state to stable storage.
Another level of persistence is to replicate persistent state to the main memory of another node in a multi-
node SLEE cluster. Persistent state may be lost if certain state replicas fail or if there is a total power fail-
ure. This level of persistence is typical in real-time communications applications because the latency to
replicate state to the memory of another node can be significantly less than storing persistent state to disk-
based stable storage.
SLEE vendors are expected to document the persistence capabilities provided by their SLEEs. For exa m-
ple, the SLEE vendor should document whether the SLEE maintains persistent state across graceful admin-
istrative shutdown and restart of the SLEE.
G.2 SLEE event model versus JavaBeans listener model

Event consumers in the JavaBeans event model subscribe for events directly with event producers via add
listener methods. In this model, an event producer has direct knowledge of its event consumers and is re-
sponsible for delivering events to the subscribed consumers.
The SLEE event model is based on the publish/subscribe model (similar to JMS). Event consumers sub-
scribe for events by attaching to Activity Contexts. Event producers publish events to Activity Contexts.
An event producer is not directly aware of its event consumers and an event consumer is not directly aware
of its event producers. The SLEE implemented Activity Contexts maintain the relationships among event
producers and event consumers.
The publish/subscribe model was chosen by the SLEE expert group because it has the following benefits:
• It allows the SLEE to know the relationships among event consumers and event producers. This
allows the SLEE to provide important value added features like garbage collection of event con-
sumers that will no longer receive events.
• It eliminates direct refe rences among event producers and event consumers. Direct references re-
duce application robustness because they introduce the possibility of invalid or dangling refer-
ences.
• It allows the SLEE to specify a single consistent event distribution model (e.g. the order of event
delivery to multiple event consumers, concurrency control semantics). A single model benefits the
developer since the developer only has a single model to learn. It also improves robustness be-
cause event producers do not have to implement e vent distribution code that complies with docu-
mented patterns or conventions.

Appendix G
• It promotes stronger decoupling or isolation of the event producer from the event consumer. This
facilitates modularity and fault isolation, i.e. an error in the event producer is less likely to propa-
gate to the event consumer and vice versa.
While the JavaBeans listener model has certain advantages, the SLEE expert group felt that the pub-
lish/subscribe model allows the SLEE to provide more value-add to event oriented applications.
G.3 SLEE originated invocation vs. non-SLEE originated invocation

design
When application code calls application code it is common for the caller to know about the set of excep-
tions that the callee can throw. In this case the caller is responsible for performing the appropriate action
based on the exception that was thrown.
This is the case for SbbLocalObject invocations, i.e. when one SBB invokes another SBB through a
SbbLocalObject contract.
When the SLEE invokes an SBB, there is no caller that knows how to perform the appropriate action if the
exception was thrown. For example the SLEE does not know how to play an announcement on a telephone
call (assuming a telephone call is the activity). Such error handling logic is application specific. Therefore
when the SLEE calls an SBB and something goes wrong, the SLEE delegates the problem back to the SBB.
This could be viewed as a circular design, but it allows the SBB developer to put their application logic in
one place (the sbbExceptionThrown method) and if the SBB developer does not like such an approach they
are free to place all event handling code in a try { ... } catch (Throwable t) { .. } statement.
SLEE always delivers events to SBBs in the context of a transaction. It is possible that the transaction rolls
back without the SBB knowing that the transaction will rollback when it is handling an event. For example
the SBB event handler method returns, and at is point of return the getRolledBackOnly() returns false. As
the SLEE attempts to commit the transaction the transaction manager refuses to commit the transaction,
because a resource involved in the transaction indicates some sort of error. In this case the environment had
a problem that the application is unaware of. Typically in call control applications transactions are used to
demarcate points in the applications state machine within a well understood failure model, and the applica-
tion is written such that if a transaction does not commit, that the application stops taking an active roll in
the call. In order to support the application stop taking an active roll in the call, the SBB developer can de-
tach from an activity or perform some other transacted operation in its sbbRolledBack callback.
G.4 Writing a sbbRolledBack method
The SBB developer should write their rolled back handler methods to cope with a transaction that contains
an event handler only, a remove only, or an event handler and remove rolling back. This can be done by
using the following approach:
public void sbbRolledBack(RolledBackContext ctx){
if ( ctx.getEvent() != null ){
// do any event handling cleanup necessary

Appendix G
}
if( ctx.isRemoveRolledBack() {
// do any cleanup necessary to handle a remove that didnt commit
}
It should be noted that whether or not any cleanup needs to be performed if a transaction committed or not
is application specific.

Glossary
Glossary
Activity An Activity object represents a related stream of events. These events

represent occurrences of significance that have occurred on the entity
represented by the Activity. From a resource’s perspective, an Activity
represents an entity within the resource that emits events on state changes
within the entity or resource.
Activity Context An Activity Context represents and encapsulates an Activity object in the
SLEE domain. An Activity Context is also a store for attributes that may
be shared by multiple SBB entities that interact with the Activity object
represented by the Activity Context. An Activity Context is also a chan-
nel that both emits events, and accepts events fired on the Activity Con-
text.
Activity Context attribute An Activity Context attribute is an attribute that an SBB component de-
fines in its SBB Activity Context Interface interface as a set of get and set
accessor methods. These accessor methods provide a type-safe mecha-
nism for accessing shareable attributes stored in Activity Contexts.
Activity Context Interface object An Activity Context Interface object is a Java object that implements the
SLEE specification defined ActivityContextInterface interface
and may optionally implement an extended SBB Developer defined SBB
Activity Context Interface interface. It provides an Activity Context with
a Java object that SBB objects can invoke. An Activity Context Interface
object can be either a generic Activity Context Interface object or an SBB
Activity Context Interface object.
Activity object An Activity object is a Java object that provides an Activity with a visible
Java API that can be invoked. Activity objects are defined, created and
owned by resources, resource adaptor entities or SLEE Facilities. The
getActivity method defined in the generic Activity Context Interface
interface returns an Activity object when invoked. Furthermore, an Activ -
ity object may be passed to an Activity Context Interface Factory object
to obtain a generic Activity Context Interface object that represents the
Activity Context of the Activity object.
ActivityContextInter- An ActivityContextInterface interface is a Java interface that is
face interface defined by the SLEE specification. It defines the operations that all SBB
objects can perform on an Activity Context. It does not declare any share-
able Activity Context attributes.
address An address is a unique identifier for an entity in a network. A common
address today is a telephone number or an IP address.
Address Profile An Address Profile is a Profile that has at least an addresses attribute
that holds an array of Address objects.
Address Profile Table An Address Profile Table contains Address Profiles and is created from
an Address Profile Specification. The Address Profile Table of a Service
contains provisioned addresses that may cause new root SBB entities of
the Service to be instantiated.

Glossary
Address Profile Specification An Address Profile Specification specifies the attributes of the Address
Profile Tables created from the Address Profile Specification. One of
these attributes must be an addresses attribute. The Java type of this
attribute must be an Address object array.
Address object An Address object represents an address and is an instance of the Ad-
dress class.
Administrator An Administrator manages the SLEE and the services running in the
SLEE through the SLEE’s management interfaces. An Administrator may
be a management client, such as a network management application, net-
work management console, or a person using a management client to
manage the SLEE.
attachment count The attachment count of a parent SBB entity is the sum of the attachment
counts of all its child SBB entities and the number of Activity Contexts
that the parent SBB entity is directly attached to.
child relation A child relation relates a child SBB to a parent SBB. It also specifies the
(in the context of SBBs) default event delivery priority for the child SBB entities created on this
child relation.
child relation A child relation relates a child SBB entity to a parent SBB entity. It also
(in the context of SBB entities) specifies the event delivery priority of child SBB entity.
custom event type A custom event type is an event type introduced by an SBB Developer.
default event delivery priority The default event delivery priority of a child relation specifies the initial
event delivery priority of an SBB entity created on the child relation.
default Profile The default Profile of a Profile Table provides the initial values for the
attributes of new Profiles of the same Profile Table.
deployable unit A deployable unit is a jar file that can be installed in the SLEE. A deploy-
able unit may contain Services, SBB jar files, event jar files, Profile
Specification jar files, resource adaptor type jar files, and resource adap-
tor jar files. Each of these jar files contain the Java class files and the de-
ployment descriptors of one or more of these components.
event An event represents an occurrence of significance that has occurred. An
event is represented in the SLEE by an event type and an event object.
event class The event class of an event object is the publicly declared Java class or
interface of the event object. The event class may not be the concrete im-
plementation class of the event object.
event delivery priority The event delivery priority of an SBB entity determines when the SBB
entity will receive an event relative to the other SBB entities that can also
receive the event.
event name An event name is an SBB scoped local name that refers to an event type.
This name must conform to the naming requirements for Java method
names. The event name of the event type is specified by the event-
name element of the event element in the SBB’s deployment descrip-
tor.
event object An event object is a Java object that represents the event and carries in-
formation to be conveyed. It cannot be a primitive Java type.

Glossary
event type The event type of an event completely determines how the SLEE will
route the event, i.e. which SBB entities will receive the event, and which
event handler methods will be invoked to process the event. All events
with the same event type are represented by event objects of the same
event class.
generic Activity Context Inter- A generic Activity Context Interface object is a Java object that imple-
face object ments the generic ActivityContextInterface interface but does
not implement an extended SBB Developer defined SBB Activity Con-
text Interface interface. It can only be used to access the underlying Ac-
tivity object of an Activity Context, attach and detach SBB entities to the
underlying Activity Context.
initial event An initial event is the event that caused the SLEE to instantiate a new
root SBB entity. This initial event is known as the initial event of the SBB
entity.
management client A management client is a program that manages the SLEE and the appli-
cations running in the SLEE through the SLEE’s management interfaces.
For example, a management client may be a network management appli-
cation or a network management console.
Object Name An Object Name is the name used to identify a specific JMX MBean ob-
ject registered with a JMX MBean Server.
Profile A Profile contains a set of attributes that hold data provisioned by the
Administrator at runtime via a management interface and is accessible by
SBB objects running in the SLEE. It exists in a Profile Table. The Profile
Specification of its Profile Table specifies its attributes and the manage-
ment interface used to provision the Profile.
Profile CMP interface A Profile CMP interface defines the attributes of each Profile in the Pro-
file Tables created from the Profile Specification that defines the Profile
CMP interface. The SBB Developer declares each attribute using a pair of
get and set accessor methods in this interface.
Profile Management abstract A Profile Management abstract class is a Java class that implements the
class Profile Management interface of the Profile Specification. It provides the
implementation of the methods declared in the SLEE specification de-
fined Profile Management interface.
Profile Management interface A Profile Management interface is a Java interface that defines the man-
agement operations (and may include the CMP field get and set accessor
methods declared in the Profile CMP interface) that interact and manipu-
late the attributes of a Profile that conforms to the Profile Specification
that defines the Profile Management interface and should be exposed
through the management interface of the Profile Specification.
Profile Management object A Profile Management object is either a Java object that is an instance of
a concrete class that extends the Profile Management abstract class if one
is provided, or a Java object that is an instance of a concrete class that
implements the Profile CMP interface and the javax.slee.pro-
file.ProfileManagement interface. It caches the persistent state of
a Profile in its CMP fields and instance variables.
Profile MBean class A Profile MBean class is a SLEE implemented class that implements the
corresponding Profile MBean interface.

Glossary
Profile MBean interface A Profile MBean interface is the external management interface that is
visible to external management clients that interact with the Profiles
specified by the Profile Specification. It is generated by the SLEE upon
Profile Specification deployment from the methods defined in the Profile
CMP interface if no Profile Management interface is provided or the Pro-
file Management interface if the Profile Management interface is pro-
vided, and the SLEE specification defined javax.slee.pro-
file.ProfileMBean interface.
Profile MBean object A Profile MBean object is an instance of a Profile MBean class.
Profile Specification A Profile Specification defines the interfaces, classes, and deployment
descriptor elements needed to define the attributes of Profiles in Profile
Tables created from the Profile Specification and the interfaces used to
provision and access a Profile of the Profile Specification.
ProfileManagement inter- The ProfileManagement interface is a SLEE specification defined
face interface that declares the life cycle methods of a Profile Management
object.
ProfileMBean interface The ProfileMBean interface is a SLEE specification defined interface
that declares the life cycle methods of a Profile MBean object.
resource adaptor A resource adaptor is an implementation of a resource adaptor type. It
mainly consists of Java classes that implements the function of adapting a
resource to the requirements of the SLEE. An Administrator installs re-
source adaptors in the SLEE.
resource adaptor entity A resource adaptor entity is an instance of a resource adaptor. Typically,
a resource adaptor. An Administrator instantiates resource adaptor entities
from resource adaptors.
resource adaptor type A resource adaptor type declares the common characteristics of a set of
resource adaptors. For example, it defines the Activity objects, the event
types, the resource adaptor interface, and the Activity Context Interface
Factory interface that are common to these resource adaptors.
Resource Info Profile Table The Resource Info Profile Table of a Service contains Service specific
information that should be passed to resource adaptors when the Service
is in the Active state.
root SBB A root SBB is an SBB that may be instantiated by the SLEE to process
events.
root SBB entity A root SBB entity is the root node in an SBB entity tree and is an instance
of a root SBB. It is instantiated by the SLEE to process its initial event.
SBB Same as SBB component.
SBB abstract class An SBB abstract class is a part of an SBB component. It contains the core
application logic of the SBB component, including how events should be
processed and the implementations of the methods declared in its SBB
local interface. It also defines the CMP fields of the SBB abstract class.

Glossary
SBB Activity Context Interface An SBB Activity Context Interface interface is a part of an SBB comp o-
interface nent. It e xtends the generic SLEE specification defined Activity-
ContextInterface interface and defines a set of get and set accessor
methods for each Activity Context attribute accessed by the SBB comp o-
nent.
SBB Activity Context Interface An SBB Activity Context Interface object is a Java object that imple-
object ments the SBB Activity Context Interface interface of an SBB comp o-
nent. It provides an Activity Context with a Java object that SBB objects
can use to access the Activity Context attributes that are defined in the
SBB Activity Context Interface interface of the SBB comp onent and
stored in the Activity Context.
SBB component An SBB component consists of a set of Java classes and interfaces, and a
deployment descriptor that describes the SBB component. These classes
and interfaces contain the SBB component’s application code.
SBB component identifier An SBB component identifier is a Java object that uniquely identifies an
SBB component.
SBB Developer An SBB Developer is a person who creates SBB components.
SBB entity An SBB entity is an instance of an SBB component. It represents the per-
s istent per-instance state of an instance of the SBB component as defined
by the CMP fields in the SBB abstract class of the SBB component.
SBB entity sub-tree. An SBB entity sub-tree is an SBB entity tree whose root is not the root
SBB entity of the SBB entity tree.
SBB entity tree An SBB entity tree is a directed acyclic graph that represents the child
relations between SBB entities. A node in this tree represents an SBB
entity. A directed edge represents the child relation from a parent SBB
entity to a child SBB entity. The label on the directed edge indicates the
event delivery priority of the child SBB entity relative to the child’s sib-
lings. The root node of this tree must be a root SBB entity.
SBB graph An SBB graph is a graph that illustrates the child relations among SBBs.
An SBB is a node in this graph and a child relation is a directed edge
from the node of the parent SBB to the node of the child SBB. Each edge
has a label that indicates the default event delivery priority of the child
relation.
SBB local interface An SBB local interface declares the methods of the SBB component that
may be invoked synchronously. The SBB Developer provides the imple-
mentation of these methods in the SBB abstract class.
SBB local object An SBB local object is an instance of a SLEE generated concrete class
that implements the SBB local interface of an SBB. This SBB local ob ject
represents an SBB entity. When invoked, it delegates the invocation to an
SBB object assigned to the SBB entity.
SBB object An SBB object is an instance of an SBB abstract class. It has a life cycle.
When an SBB object is in the Ready state, the SBB object has been as-
signed to an SBB entity. It executes on behalf of the SBB entity and it can
access the persistent state of the SBB entity.

Glossary
SbbContext object The SbbContext object of an SBB object gives the SBB object access
to the SBB object’s context maintained by the SLEE, allows the SBB
object to invoke functions provided by the SLEE. It also allows the SBB
object to obtain runtime information about the SBB entity assigned to the
SBB object.
Service Same as Service component.
Service component A Service component specifies a child relation from the SLEE (as the
logical parent of all root SBBs) to a root SBB, the default event delivery
priority of the Service, and provides other information needed by the
SLEE to instantiate root SBB entities of the Service, such as the Service’s
Address Profile Table and Resource Info Profile Table.
Service Deployer A Service Deployer is a person who customizes SBBs and Services for
deployment into the target operational environment.
Service component identifier A Service component identifier is a Java object that uniquely identifies a
Service component.
subscriber A subscriber is an entity; it may be a person, business etc.

Jain - Slee 1 - 0 FR Spec

Uploaded by

Copyright:

Available Formats

Jain - Slee 1 - 0 FR Spec

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Jain - Slee 1 - 0 FR Spec

Uploaded by

Copyright:

Available Formats

JAIN SLEE 1.

Swee Boon Lim

Copyright 2001-2002 Sun Microsystems, Inc.

Copyright 2001-2002 Open Cloud Limited

All rights reserved

Chapter 2 Overview ............................................................................5

JAIN SLEE 1.0 Specification, Final Release Page iii

2.3.1 SBB Developer ............................................................................................................................17

Chapter 3 Putting it Together ........................................................... 18

JAIN SLEE 1.0 Specification, Final Release Page i v

Chapter 5 SBB Local Interface ......................................................... 43

Chapter 6 The SBB Abstract Class ................................................... 48

JAIN SLEE 1.0 Specification, Final Release Page v

Chapter 7 Activity Objects, Activity Contexts, and Activity Context

JAIN SLEE 1.0 Specification, Final Release Page vi

7.3.2 Activity Context operations.......................................................................................................83

Chapter 8 Events ............................................................................... 99

JAIN SLEE 1.0 Specification, Final Release Page vii

8.2 Events and Activity Contexts ..................................................................................................102

Chapter 9 Transactions ................................................................... 122

JAIN SLEE 1.0 Specification, Final Release Page viii

9.5.6 Rolled Back state.......................................................................................................................124

Chapter 10 Profiles and Profile Specifications.................................. 136

JAIN SLEE 1.0 Specification, Final Release Page ix

10.8 Profile Management abstract class .........................................................................................146

Chapter 11 Usage Parameters........................................................... 162

JAIN SLEE 1.0 Specification, Final Release Page x

11.4.2 Get SBB Usage Parameter method example ........................................................................166

Chapter 12 Runtime Environment .................................................... 167

Chapter 13 Facilities ......................................................................... 171

Chapter 14 Management................................................................... 193

JAIN SLEE 1.0 Specification, Final Release Page xi

JAIN SLEE 1.0 Specification, Final Release Page xii

Chapter 15 Resource Adaptors ......................................................... 238

Appendix A Event Router Formal Model .......................................... 249

JAIN SLEE 1.0 Specification, Final Release Page xiii

A.3.8 Uniqueness of SBB entities with respect to child relation objects....................................253

Appendix B Event Router Pseudo Code............................................. 258

Appendix C JCC Resource Adaptor Type ......................................... 265

JAIN SLEE 1.0 Specification, Final Release Page xiv

Appendix D JAIN SIP Resource Adaptor Type ................................. 267

Appendix E JAIN TCAP Resource Adaptor Type............................. 270

Appendix F Integration with EJB applications.................................. 273

Appendix G Frequently Asked Questions........................................... 276

Glossary ........................................................................................ 279

JAIN SLEE 1.0 Specification, Final Release Page xv

1.1 Target audience

1.2 Typographic and terminology conventions

JAIN SLEE 1.0 Specification, Final Release Page 1

JAIN SLEE 1.0 Specification, Final Release Page 2

JAIN SLEE 1.0 Specification, Final Release Page 3

1.7 Relationship with JAINTM

JAIN SLEE 1.0 Specification, Final Release Page 4

2.1 Scope of the SLEE specification

2.1.1 Component model

2.1.1.1 Events and event types

2.1.1.2 Event driven applications

2.1.1.3 Application components

2.1.2 Provisioned data