SCA_EJBSessionBeanBinding_V100

SSSCCCAAA SSSeeerrrvvviiiccceee CCCooommmpppooonnneeennnttt AAArrrccchhhiiittteeeccctttuuurrreee EJB Session Bean Binding SCA Version 1.00, February 22 2007 Technical Contacts: Ron Barack SAP AG ron.barack@sap.com Henning Blohm SAP AG henning.blohm@sap.com Dave Booz IBM Corporation booz@us.ibm.com Rashmi Hunt IBM Corporation hrashmi@us.ibm.com Michael Keith Oracle Corporation michael.keith@oracle.com Michael Rowley BEA Systems, Inc. mrowley@bea.com SCA Service Component Architecture EJBSessionBeanBinding Specification V1.00 February 2007 ii Copyright Notice © Copyright BEA Systems, Inc., Cape Clear Software, International Business Machines Corp, Interface21, IONA Technologies, Oracle, Primeton Technologies, Progress Software, Red Hat, Rogue Wave Software, SAP AG., Siemens AG., Software AG., Sun Microsystems, Inc., Sybase Inc., TIBCO Software Inc., 2005, 2006, 2007. All rights reserved. License The Service Component Architecture Specification is being provided by the copyright holders under the following license. By using and/or copying this work, you agree that you have read, understood and will comply with the following terms and conditions: Permission to copy, display and distribute the Service Component Architecture Specification and/or portions thereof, without modification, in any medium without fee or royalty is hereby granted, provided that you include the following on ALL copies of the Service Component Architecture Specification, or portions thereof, that you make: 1. A link or URL to the Service Component Architecture Specification at this location : • http://www.osoa.org/download/attachments/35/ SCA_AssemblyModel_V100.pdf 2. The full text of the copyright notice as shown in the Service Component Architecture Specification. BEA, Cape Clear, IBM, Interface21, IONA, Oracle, Primeton, Progress Software, Red Hat, Rogue Wave, SAP, SIEMENS AG, Software AG., Sun Microsystems, Sybase, TIBCO (collectively, the “Authors”) agree to grant you a royalty-free license, under reasonable, non-discriminatory terms and conditions to patents that they deem necessary to implement the Service Component Architecture Specification. THE Service Component Architecture SPECIFICATION IS PROVIDED "AS IS," AND THE AUTHORS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SPECIFICATION AND THE IMPLEMENTATION OF ITS CONTENTS, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT OR TITLE. THE AUTHORS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR RELATING TO ANY USE OR DISTRIBUTION OF THE Service Components Architecture SPECIFICATION. The name and trademarks of the Authors may NOT be used in any manner, including advertising or publicity pertaining to the Service Component Architecture Specification or its contents without specific, written prior permission. Title to copyright in the Service Component Architecture Specification will at all times remain with the Authors. No other rights are granted by implication, estoppel or otherwise. SCA Service Component Architecture EJBSessionBeanBinding Specification V1.00 February 2007 iii Status of this Document This specification may change before final release and you are cautioned against relying on the content of this specification. The authors are currently soliciting your contributions and suggestions. Licenses are available for the purposes of feedback and (optionally) for implementation. IBM is a registered trademark of International Business Machines Corporation in the United States, other countries, or both. BEA is a registered trademark of BEA Systems, Inc. Cape Clear is a registered trademark of Cape Clear Software IONA and IONA Technologies are registered trademarks of IONA Technologies plc. Oracle is a registered trademark of Oracle USA, Inc. Progress is a registered trademark of Progress Software Corporation Red Hat is a registered trademark of Red Hat Inc. Rogue Wave is a registered trademark of Quovadx, Inc SAP is a registered trademark of SAP AG. SIEMENS is a registered trademark of SIEMENS AG Software AG is a registered trademark of Software AG Sun and Sun Microsystems are registered trademarks of Sun Microsystems, Inc. Sybase is a registered trademark of Sybase, Inc. TIBCO is a registered trademark of TIBCO Software, Inc. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Other company, product, or service names may be trademarks or service marks of others. SCA Service Component Architecture EJBSessionBeanBinding Specification V1.00 February 2007 iv Table of Contents SCA Service Component Architecture.........................................................................................i Copyright Notice.................................................................................................................. ii License .............................................................................................................................. ii Status of this Document ...................................................................................................... iii 1 Overview .........................................................................................................................1 2 Session Bean Binding ........................................................................................................2 2.1 Session Bean Binding Schema ....................................................................................2 2.2 Interface Mapping.....................................................................................................3 2.2.1 EJBObject and EJBLocalObject Interfaces..................................................................4 2.2.2 Stateful Session Bean Home Interface......................................................................4 2.3 Reference Binding.....................................................................................................5 2.3.1 Conversational Nature of Stateful Session Beans .......................................................5 2.3.2 Exception Handling ................................................................................................6 2.3.3 Packaging.............................................................................................................6 2.4 Service Binding.........................................................................................................7 2.4.1 Handling methods from EJBObject and EJBLocalObject ...............................................8 3 Appendix A - Use Cases...................................................................................................10 3.1 Consuming an Existing EJB SOA Service ....................................................................10 3.2 Exposing an SCA Service with an EJB SCA Binding ......................................................10 3.3 Consuming Existing Local EJB SOA Services ...............................................................12 3.4 Exposing an SCA Service with a Local SLSB SCA Binding .............................................12 3.5 Consuming an EJB Service inside a Java EE EAR file ....................................................13 3.6 Exposing an SCA Service inside a Java EE EAR file ......................................................14 4 Appendix B - EJB Binding Schema.....................................................................................16 5 References.....................................................................................................................17 SCA Service Component Architecture EJBSessionBeanBinding Specification V1.00 February 2007 1 1 Overview 1 2 EJB session beans are a common technology used to implement business services. The ability to 3 integrate SCA with session bean based services is useful because it preserves the investment 4 incurred during the creation of those business services, while enabling the enterprise to embrace 5 the newer SCA technology in incremental steps. The simplest form of integration is to simply 6 enable SCA components to invoke session beans as SCA services. There is also a need to expose 7 SCA services such that they are consumable by programmers skilled in the EJB programming 8 model. This enables existing session bean assets to be enhanced to exploit newly deployed SCA 9 services without the EJB programmers having to learn a new programming model. 10 This document explains the EJB SCA binding. This proposal describes how to integrate a 11 previously deployed session bean into an SCA assembly, and how to expose SCA services to 12 clients which use the EJB programming model. 13 The EJB programming model supports stateful and stateless session beans. Stateful session 14 beans can implement a conversational interaction with their clients. Stateless session bean are 15 not conversational and instances may receive calls from any number of clients in any order. 16 The EJB binding supports the stateless session bean model as well as the stateful session bean 17 model. 18 The EJB Session Bean binding enables: 19 • SCA developers to treat previously deployed session beans as SCA services, by wiring them 20 into an SCA assembly (SCA reference). 21 • SCA service deployers to expose a SCA service as a session bean for consumption by Java EE 22 applications. 23 24 The use of EJBs and EJB modules as SCA component implementations is beyond the scope of this 25 specification and is described in the Java EE integration specification [1]. The following diagram 26 shows the use of the EJB SCA binding on both services and references. 27 28 Composite A Component AService EJB SB Binding EJB SB Binding Component B Reference 29 Figure 1: EJB Binding used on Services and References 30 31 SCA Service Component Architecture EJBSessionBeanBinding Specification V1.00 February 2007 2 2 Session Bean Binding 32 33 2.1 Session Bean Binding Schema 34 35 The EJB session bean binding element is defined by the following pseudo-schema. 36 37 38 48 49 50 51 52 53 • /binding.ejb/@homeInterface - the homeInterface attribute of the EJB binding is the 54 session bean’s home interface, and is used when exposing SCA services as EJB 2.x session 55 beans. 56 57 • /binding.ejb/@ejb-link-name - the ejb-link-name attribute provides a means for 58 integrating EJB reference resolution with SCA. When used on a binding for a reference, it 59 allows a SCA client to bind to an EJB that is packaged in the same Java EE EAR file as the 60 SCA client. When used on a service binding, it exposes an target for Java EE 61 clients that want to use Java EE assembly to wire to the SCA service. This attribute is 62 functionally equivalent to using the subelement of the element in an 63 EJB deployment descriptor. The value of this attribute is supplied by an application 64 assembler, and is in the form as specified by the Java EE specification (i.e. #). 66 67 • /binding.ejb/@session-type – the session-type attribute is used to indicate the kind of 68 session bean contract to be used when referencing a session bean or when exposing as a 69 session bean. The default is “Stateless”. Admissible values are “Stateless” and “Stateful”. It is 70 not necessary to specify the attribute, if it can be inferred from the interface of the reference 71 or service. If the latter is conversational, the stateful session bean contract applies, and if it is 72 not conversational, the stateless session bean contract applies. A mismatch of the attribute 73 value and interface provided meta-data will raise an IllegalStateException at latest at 74 runtime. See also the section Interface Mapping. 75 76 • /binding.ejb/@ejb-version – the ejb-version attribute is used to indicate the EJB client 77 view exposed by the EJB binding when used on an SCA service. This attribute has no 78 meaning when used on a reference. The value ‘EJB2’ indicates that an EJB client MUST 79 interact with the binding using the EJB 2.x client view. The value ‘EJB3’ indicates the desire 80 to expose an EJB 3.0 client view. 81 82 SCA Service Component Architecture EJBSessionBeanBinding Specification V1.00 February 2007 3 83 The base SCA binding schema provides an attribute called uri, that is used to denote the URI of 84 an endpoint. In the context of the SCA EJB binding, the uri attribute is defined as follows: 85 86 • /binding.ejb/@uri – optional attribute that specifies the URI of a session bean endpoint. 87 For EJB 2.x, this is the endpoint of the session home. For interoperability the form of the URI 88 is defined by CORBA in the CORBA Services specification [2], and is a standard URI form for 89 referring to remotable CORBA objects. Briefly, the corbaname URI format looks like this: 90 o corbaname:iiop::/# 91 92 Typically, a corbaname URI doesn’t include all these components. The following example 93 shows a corbaname URI that uses the default ORB configuration to find an EJB home at 94 ejb/MyHome in the JNDI directory: 95 96 o corbaname:rir:#ejb/MyHome 97 98 Other forms of URI specification are admissible when interoperability is of no concern. 99 100 101 102 2.2 Interface Mapping 103 104 When used with the EJB binding, a service or reference interface must be compatible with a 105 session bean interface, according to the following rules: 106 107 • The interface offered by a reference MUST be remotable if the remote session bean interface 108 is being accessed, and MUST be local if the local session bean interface is being accessed. 109 • The methods on the session bean MUST be a compatible superset of the methods in the 110 interface used by the reference. 111 • The interface used by a reference MAY NOT contain any methods inherited from EJBObject or 112 EJBLocalObject. 113 • Compatibility for an individual method is defined by the SCA Assembly Model Specification 114 [4], and can be stated simply as compatibility of the signature. That is, the method name, 115 input types, and output types MUST be identical. 116 • The order of the input and output types also MUST be identical. 117 • Except for RemoteExceptions, the set of Faults and Exceptions declared by the SCA reference 118 interface MUST be the same or a superset of those specified by the EJB interface. 119 • The interface offered by a service or reference with an EJB binding MUST NOT be 120 conversational in the case of a stateless session bean and MUST be conversational in the case 121 of a stateful session bean (exposure and consumption). 122 SCA Service Component Architecture EJBSessionBeanBinding Specification V1.00 February 2007 4 • The interface offered by a service or reference MAY be an SCA business interface or an EJB 123 3.0 remote or local interface. The interface is considered non-conversational unless one of 124 the following conditions applies: 125 o The interface is marked as conversational using the @Conversational SCA annotation. 126 o The binding.ejb element has an attribute session-type with value “Stateful”. 127 • For bindings that consume EJB 3.0 beans, any method marked with the @endsConversation 128 annotation in the interface used by a reference MUST map to a method marked with 129 @Remove in the session bean’s implementation class. The interface used by a reference 130 SHOULD contain @endsConversation annotations on all methods that map to @Remove 131 methods in the session bean’s implementation class. This assures that the resources 132 associated with the binding are freed when the bean is no longer needed. 133 134 2.2.1 EJBObject and EJBLocalObject Interfaces 135 The interfaces exposed from EJB 2.X beans inherit from either EJBObject or EJBLocalObject. 136 EJBObject and EJBLocalObject contain methods directed toward the management of bean 137 instances, meaning that the exposed 2.X interfaces mix business and infrastructure methods in a 138 way that makes them poorly suited for use in SCA assemblies. EJB 2.X beans developed using 139 the “Business Interface Pattern” will already have an interface that is suitable for SCA assembly. 140 In other cases, a suitable interface may be quickly derived from the SessionBean interface. 141 However, the session bean interface itself cannot be used as the interface of a reference binding. 142 143 When SCA Services are exposed as EJB 2.X session beans, the exposed interface will inherit from 144 EJBObject or EJBLocalObject. Section 2.4 describes the behavior associated with each inherited 145 method. 146 2.2.2 Stateful Session Bean Home Interface 147 SCA services have no support for a concept like EJB home interfaces. Existing EJB 2.x stateful 148 session beans may however rely on the use of home interface Create methods for 149 initialization. In order to accommodate the use of the home interface for stateful session beans, 150 the following rules apply: 151 152 • Methods offered by the reference interface that are of the form 153 create(*) and that do not match any method on the EJB local or remote 154 business interface, according to the rules above, but do match a create 155 method on the bean’s corresponding local or remote home interface are mapped to that 156 matching home interface method. This mapping ignores javax.ejb.CreateExceptions. 157 158 • A call to such a method on a given service reference starts an SCA conversation and 159 creates a new session object for the stateful session bean by forwarding the call to the 160 mapped home interface create method. 161 162 See also the section Conversational Service of a Stateful Session Bean for more details on 163 conversations over stateful session beans via the EJB binding. 164 165 166 SCA Service Component Architecture EJBSessionBeanBinding Specification V1.00 February 2007 5 2.3 Reference Binding 167 168 When used on a reference, the EJB binding specifies the means for connecting an SCA 169 component to a previously deployed or co-deployed session bean. 170 171 The reference interface used with the EJB binding can be either a remote or local session bean 172 interface. SCA deployment logic and the binding implementation will introspect the reference 173 interface class to determine whether it is local or remote. If an SCA component needs to