| ------------------------------- |
| Apache OpenWebBeans M3 |
| ------------------------------- |
| This readme file contains an information regarding to the "M3" version of the |
| Apache OpenWebBeans project. |
| |
| -------------------------------- |
| What is an OpenWebBeans? |
| -------------------------------- |
| OpenWebBeans is an ASL-License implementation of the JSR-299, Contexts and Dependency Injection for the Java EE platform. |
| |
| Project web page could be found at the URL : |
| "http://incubator.apache.org/projects/openwebbeans.html" |
| |
| -------------------------------- |
| OpenWebBeans M3 Release Features |
| -------------------------------- |
| |
| - M3 Release Supports the followings |
| ----------------------------------- |
| * Managed Beans Support |
| * Session Beans Support (via Embeddable OpenEJB container in Tomcat) |
| * Producer Method Support |
| * Producer Field Support |
| * Java EE Resource Injection Support |
| * JMS OpenWebBeans Support(OWB Specific) |
| * Inheritance, Stereotype Inheritances |
| * Specialization Support |
| * Event Support |
| * Decorator and Interceptor Support |
| * Lookup and Dependency Injection Support |
| * Java EE Plugin Support (via ServetContextListener interface) |
| * Portable Integration Support |
| |
| - M3 Release Does not Supports the followings |
| -------------------------------------------- |
| * Injection into other Java EE 6 non-contextual components |
| * Passivation Capability of Beans |
| * Using @Alternative instead of @DeploymentType |
| * Does not fully integrated with Geronimo |
| (You have to configure your application to use OWB functionality, |
| e.g configure web.xml, adding interceptor to EJBs etc.) |
| |
| ------------------------------------------- |
| Release Notes - OpenWebBeans - Version M3 |
| ------------------------------------------- |
| Sub-task |
| |
| * [OWB-74] - support @PersistenceContext JPA injection |
| |
| Bug |
| |
| * [OWB-59] - Review the handling of ConversationScope timeouts |
| * [OWB-95] - rename exceptions to fit specification |
| * [OWB-121] - remove JMS specific namings from OpenWebBeansPlugin |
| * [OWB-123] - remove StereoType restrictions |
| * [OWB-124] - ClassCastExceptoin during deployment |
| * [OWB-132] - atinject license header formatting breaks build |
| |
| Improvement |
| |
| * [OWB-65] - Java EE Namespace Support |
| * [OWB-92] - facor out all EJB specific parts into an own maven module |
| * [OWB-96] - EntityManager WebBeans Component |
| * [OWB-105] - Improve Injection Resolver for Generic Classes |
| * [OWB-108] - Update InjectionPoint interface |
| * [OWB-109] - Update Instance Interface |
| * [OWB-110] - Update Creational Context Interface |
| * [OWB-111] - Update Contextual Interface |
| * [OWB-112] - Check Usage of Creational Context |
| * [OWB-113] - Dependent Context Active State |
| * [OWB-114] - Check Contextual Reference Object Return Type |
| * [OWB-117] - Updates Event For Last Draft |
| |
| New Feature |
| |
| * [OWB-5] - EJB Web Beans |
| * [OWB-43] - Constructor Parameter Injection For primitive/wrappers |
| * [OWB-130] - implement JSR-330 annotations for OWB |
| * [OWB-131] - integrate new JSR-330 annotations within OWB |
| |
| Task |
| |
| * [OWB-2] - XML Configuration |
| * [OWB-8] - Common Annotations |
| * [OWB-12] - Update WebBeans Lifecycle for EJB Beans |
| * [OWB-13] - Update WebBeans Lifecycle for JMS Beans |
| * [OWB-47] - Java EE Resource Injection Support |
| * [OWB-64] - Asynhronous Event Support via JMS |
| * [OWB-66] - Schema Validation |
| * [OWB-68] - Support for Child Managers |
| * [OWB-115] - Contextual Reference Validity |
| * [OWB-119] - Cover Chapter11 SPI Implementations |
| * [OWB-120] - Implement Chapter12 Initialization Events |
| |
| ---------------------------------------------- |
| Required Platform |
| ---------------------------------------------- |
| Java Version : Java SE >= 6.0 |
| Java EE Must : Java EE >= 5.0 |
| |
| --------------------------------------------- |
| How to Configure The OpenWebBeans |
| --------------------------------------------- |
| |
| This section explains a content of the distribution bundle, OWB plugins and its |
| dependent libraries. |
| |
| --------------------------------------------- |
| M3 Bundle Content |
| --------------------------------------------- |
| There are several jars in the OpenWebBeans M3 distribution; |
| |
| - atinject-api-1.0.0-incubating-M3.jar --> Includes JSR-330 API |
| - openwebbeans-api-1.0.0-incubating-M3.jar --> Includes JSR-299 API |
| - openwebbeans-impl-1.0.0-incubating-M3.jar --> Includes Core Dependency Injection Service |
| - openwebbeans-ejb-1.0.0-incubating-M3.jar --> EJB Plugin(Supports EJBs in OpenEJB embedded in Tomcat) |
| - openwebbeans-jms-1.0.0-incubating-M3.jar --> JMS Plugin(Supports injection of JMS related artifacts) |
| - openwebbeans-jpa-1.0.0-incubating-M3.jar --> JPA Plugin(Non JTA Entity Manager Support)This is @Deprecated,use Resource Plugin. |
| - openwebbeans-jsf-1.0.0-incubating-M3.jar --> JSF Plugin(JSF Conversation Scoped Support) |
| - openwebbeans-resource-1.0.0-incubating-M3.jar --> Java EE Resource Injection Plugin |
| - openwebbeans-geronimo-incubating-M3.jar --> Geronimo Integration(In early stage,includes supports for OpenEJB resource injections) |
| |
| |
| ------------------------------------------ |
| How OWB Plugins Work |
| ------------------------------------------ |
| |
| OpenWebBeans has been developing as a plugin way. Core dependency injection service |
| is provided with the JSR-299 API and Core mplementation jars. If you need further service functionality, |
| you have to add respective plugin jars into the application classpath. Plugin functionality uses Java SE 6.0 |
| "java.util.ServiceLoader" utility. |
| |
| ------------------------------------------ |
| Dependent Libraries |
| ------------------------------------------ |
| |
| Third Party jars: |
| They are necessary at runtime in the Core Implementation. |
| |
| log4j: Version 1.2.14 |
| dom4j: Version 1.6.1 |
| javassist : Version 3.8.0.GA |
| scannotation : Version 1.0.2 |
| |
| Java EE APIs jars : |
| Generally full Java EE servers provides these jars. But web containers like Tomcat or Jetty |
| does not contain some of them, such as JPA, JSF api etc. So, if you do not want to bundle |
| these libraries within your application classpath, you have to put these libraries into your |
| server common classpath if it does not contain as built-in. |
| |
| servlet-2.5 --> Core implementation |
| ejb-3.0 --> EJB Plugin |
| el-1.0 --> JSR-299 API, Core Implementation |
| jsf-1.2 --> JSF Plugin |
| jsr-250 --> Core implementation |
| interceptor-3.0 --> JSR-299 API, Core implementation |
| jta-1.1 --> Core implementation |
| jsp-2.1 --> Core implementation |
| jpa-3.0 --> Resource Plugin |
| jaxws-2.1 --> Resource Plugin |
| jms-1.1 --> JMS Plugin |
| |
| ------------------------------------------ |
| Library Configuration |
| ------------------------------------------ |
| To run openwebbeans applications in the Java EE based application server, |
| you could add JSR-299 API and JSR-330 API into the server common classpath, and |
| implementation, plugins and dependent jars into your "WEB-INF/lib" directory |
| of the Java EE Web Application. |
| |
| In this release, we can not support the OpenWebBeans as an integrated |
| functionality of the Java EE Application Servers. So, you have to manage the |
| configuration of the OpenWebBeans within your application's "web.xml" file. A sample "web.xml" |
| file can be found in the "config" directory. To use EJB functionality, you also have to |
| add OWB specific interceptor into your EJB beans. Look at EJB section for further details. |
| |
| --------------------------------------------- |
| OpenWebBeans Properties File |
| --------------------------------------------- |
| OpenWebBeans uses a default configuration file to configure some of its |
| properties. Default configuration file is embedded into the OWB implementation |
| jar file. Instead of opening this jar file and changing configuration properties, simply add |
| "openwebbeans.properties" file into a "META-INF/" folder of your application |
| classpath. This will override the default configuration. |
| |
| Belows are all configuration properties of the OpenWebBeans: |
| |
| - "org.apache.webbeans.spi.JNDIService" : Configures JNDI provider implementation. |
| Values : org.apache.webbeans.spi.ee.JNDIServiceEnterpriseImpl, org.apache.webbeans.spi.se.JNDIServiceStaticImpl |
| Default: org.apache.webbeans.spi.se.JNDIServiceStaticImpl |
| |
| - "org.apache.webbeans.spi.JNDIService.jmsConnectionFactoryJndi" : Configures JMS ConnectionFactory object jndi name |
| Values : Server specific JNDI name |
| Default: ConnectionFactory |
| |
| - "org.apache.webbeans.conversation.Conversation.periodicDelay" : Conversation removing thread periodic delay |
| Values : Configured in millisecond |
| Default: 150000 ms |
| |
| - "org.apache.webbeans.spi.TransactionService" : Transaction Service implementation for getting transaction manager and transaction |
| Values : org.apache.webbeans.spi.ee.TransactionServiceJndiImpl, org.apache.webbeans.spi.se.TransactionServiceNonJTA |
| Default: org.apache.webbeans.spi.ee.TransactionServiceJndiImpl |
| |
| - "org.apache.webbeans.resource.spi.ResourceService" : Java EE Resource Injection Service |
| Values : org.apache.webbeans.resource.spi.se.ResourceServiceImpl, org.apache.webbeans.spi.ee.openejb.resource.OpenEjbResourceServiceImpl |
| Default: org.apache.webbeans.resource.spi.se.ResourceServiceImpl |
| |
| - "org.apache.webbeans.spi.deployer.MetaDataDiscoveryService" : Discovers annotations and configuration files |
| Values : Implementation of org.apache.webbeans.spi.deployer.MetaDataDiscoveryService SPI |
| Default: org.apache.webbeans.spi.ee.deployer.WarMetaDataDiscoveryImpl for war and Collapsed ear in OpenEJB in Tomcat. |
| |
| - "org.apache.webbeans.spi.deployer.UseEjbMetaDataDiscoveryService" : Use EJB functionality or not. If use OpenEJB configures to true |
| Values : false, true |
| Default: false |
| |
| - "org.apache.webbeans.useOwbSpecificXmlConfig" : Use OWB specific XML configuration. OWB also supports its own XML configuration. |
| In future, you can configure beans via OWB specific XML configuration. Default is ok for the time being. |
| Values : false, true |
| Default: false |
| |
| - "org.apache.webbeans.fieldInjection.useOwbSpecificInjection" : Use @Inject on injection fields or not. If this set to true |
| you can inject object into beans without @Inject. |
| Values : false, true |
| Default: false |
| |
| - "org.apache.webbeans.spi.conversation.ConversationService": Implementation of conversation. |
| Values : Any custom implementation of org.apache.webbeans.spi.conversation.ConversationService |
| Default: org.apache.webbeans.spi.conversation.jsf.JSFConversationServiceImpl |
| |
| --------------------------------------------- |
| EJB Support via Embeddable OpenEJB Container in Tomcat 6.X |
| --------------------------------------------- |
| |
| Configuration Steps: |
| -------------------------------------------- |
| 1* Download Tomcat 6.X version |
| 2* Configure OpenEJB. Look at URL http://openejb.apache.org/tomcat.html for installation. |
| 3* Copy "atinject-api-1.0.0-incubating-M3.jar" to Tomcat /lib folder. |
| 4* Copy "openwebbeans-api-1.0.0-incubating-M3.jar" |
| 5* Look at ejb-sample.war for "WEB-INF/lib" libraries to develop custom application. |
| You can also look at a source of the project. |
| |
| To use EJB functionality, you will use OpenEJB collapse-ear support. In this configuration, |
| your EJB beans live within your "war" bundle. |
| |
| How to Develop EJB Applications |
| --------------------------------------------- |
| 1* Add "META-INF/openwebbeans.properties" into your application classpath. |
| 2* Add "org.apache.webbeans.spi.deployer.UseEjbMetaDataDiscoveryService=true" to use EJB functionality. |
| So OWB container looks for EJBs. |
| 3* Add "org.apache.webbeans.resource.spi.ResourceService=org.apache.webbeans.spi.ee.openejb.resource.OpenEjbResourceServiceImpl" to |
| use OpenEJB Resource injections. |
| 4* Add "openwebbeans-ejb", "openwebbeans-resource" and "openwebbeans-geronimo" plugins into your web application classpath. |
| It adds EJB, Resource and Open EJB Resource plugins into your application. |
| 5* If you want to use other plugins, add respective plugins into your application classpath. For example, if you wish to use |
| JSF framework, you add "openwebbeans-jsf" plugin. |
| 6* Add OWB related interceptor into your EJB Beans. This is called "org.apache.webbeans.ejb.interceptor.OpenWebBeansEjbInterceptor" |
| This is needed for OWB injections. |
| 7* Update your application's "web.xml" to add OWB specific configuration. |
| |
| --------------------------------------------- |
| How to Run Samples |
| --------------------------------------------- |
| |
| In this release, there are four sample applications located in the "/samples" directory |
| of the distribution. "Guess","Reservation" and "Ejb Sample" applications contains pure |
| sources. You have to execute mvn builds to run them. "Jms Sample" contains war file. |
| You can directly deploy it into the container. |
| |
| 1) "Guess Application" : Simple usage of the OWB + JSF. |
| It can be run in the jetty web container via maven jetty plugin from source. |
| Look at "Compile and Run Samples via Jetty&Tomcat Plugin" section. |
| |
| 2) "Hotel Reservation Application" : Show usage of JSF + JPA + OWB |
| It can be run in the jetty web container via maven jetty plugin from source. |
| Look at "Compile and Run Samples via Jetty&Tomcat Plugin" section. |
| |
| 3) "EJB Sample Application" : Shows the usage of EJBs with embeddable OpenEJB in Tomcat. Firstly |
| configure OpenEJB with Tomcat as explained above. |
| Look at "Compile and Run Samples via Jetty&Tomcat Plugin" section |
| |
| 4) "JMS Injection Sample" : Show JMS injections. JMS injection currently uses |
| ConnectionFactory as JMS connection factory jndi name. You can change this |
| via configuration file. Look above explanation for how to configure JMS jndi. Also, |
| JMS injection requires to use of a JMS provider. Generally Java EE servers contains |
| default JMS provider. It can be run on JBoss and Geronimo. Simple drops "samples/jms-sample.war" |
| into Java EE server deploy folder. Also it uses Queue with jndi_name = "queue/A". So you have to |
| create a queue destination in your JMS provider with name "queue/A" to run example. If you |
| want to change queue jndi name, then look at source and change it from "WEB-INF/beans.xml" file. |
| |
| Configuring and Running the Applications: |
| -------------------------------------------- |
| See section Compile and Run Samples via Jetty&Tomcat Plugin. |
| |
| Library Dependencies |
| -------------------------------------------- |
| "Third party" jars are included within the WAR deployment(In WEB-INF/lib). |
| But it still requires the "lib/javaee" Java EE API jars for running sucessfully. |
| If your server does not include any of them, simply take the necessary jar from the "lib/javaee" and |
| put it into your server classpath. |
| |
| -------------------------------------------- |
| Maven Install and Package From the Source |
| -------------------------------------------- |
| |
| Maven Version : Apache Maven 2.2.1 |
| |
| Firstly you have to download the "source/all" version of the OpenWebBeans project that |
| contains the all source codes of the OpenWebBeans. |
| |
| To install the Maven artifacts of the project from the source, Maven must be installed |
| in your runtime. After Maven installation, just run the following command in the top level |
| directory that contains the main "pom.xml" : |
| |
| > mvn clean install |
| |
| This command will install all the Maven artifacts into your local Maven repository. |
| |
| If you wish to package all artifacts of the project, just run the following command |
| in in the top level directory that contains the main "pom.xml" : |
| |
| > mvn clean package |
| |
| This command will package the project artifacts from the source and put these artifacts into the each modules |
| respective "target" directory. |
| |
| ------------------------------------------- |
| Compile and Run Samples via Tomcat&Jetty Plugin |
| ------------------------------------------- |
| |
| Samples Run within Jetty Plugin |
| ------------------------------------------ |
| You can compile and run "guess" and "reservation "samples via maven Jetty plugin. |
| Go to the source bundle "samples/" directory. In the "guess/" or "reservation/" directory, run |
| the following maven commands. It will start up maven Jetty container. It bundles all of the |
| required jars into the WEB-INF/lib folder. You are not required to add any jar to the classpath. |
| |
| > mvn clean install -Pjetty |
| > mvn jetty:run -Pjetty |
| |
| Guess URL : http://localhost:8080/guess |
| Reservation URL : http://localhost:8080/reservation |
| |
| Samples Run within Tomcat Plugin |
| ------------------------------------------ |
| You can also compile and run "ejb-sample" example via Tomcat plugin. Tomcat |
| plugin uses http://localhost:8080/manager application to deploy war file |
| into your embeddable EJB Tomcat container. There must be an tomcat-users.xml |
| file in the "conf" directory of the server that contains manager role and username. |
| |
| >Start Tomcat server if not started |
| >mvn tomcat:deploy |
| |
| Ejb Sample URL : http://localhost:8080/ejb-sample |
| |
| Example tomcat-users.xml file |
| ------------------------------------------ |
| <tomcat-users> |
| <role rolename="manager"/> |
| <user username="admin" password="" roles="manager"/> |
| </tomcat-users> |
| |
| ----------------------------------------- |
| Deploy JMS Sample |
| ----------------------------------------- |
| Simple drops jms-sample.war file into your application deploy location. |
| |
| JMS Sample Example URL : Hit the url http://localhost:8080/jms-sample/sender.jsf for sending JMS messages |
| Hit the url http://localhost:8080/jms-sample/receiver.jsf for receiving JMS messages |
| |
| ----------------------------------------------- |
| OpenWebBeans User and Development Mailing Lists |
| ----------------------------------------------- |
| Please mail to the user mailing list about any questions or advice |
| about the OpenWebBeans. |
| |
| User Mailing List : [openwebbeans-users@incubator.apache.org] |
| |
| You can also join the discussions happening in the dev list |
| |
| Dev Mailing List : [opwnwebbeans-dev@incubator.apache.org] |
| |
| ------------------------------------------- |
| OpenWebBeans JIRA Page |
| ------------------------------------------- |
| Please logs bugs into the "https://issues.apache.org/jira/browse/OWB". |
| |
| ------------------------------------------ |
| OpenWebBeans Wiki and Blog Page |
| ----------------------------------------- |
| Wiki: http://cwiki.apache.org/OWB/ |
| Introduction to OpenWebBeans : http://cwiki.apache.org/OWB/introduction-to-openwebbeans.html |
| Blog : http://blogs.apache.org/owb |
| |
| ----------------------------------------- |
| OpenWebBeans Web Page |
| ---------------------------------------- |
| You can reach the OpenWebBeans web page at |
| http://incubator.apache.org/openwebbeans. |