Repository: deltaspike Updated Branches: refs/heads/master 6b39550ce -> 88fdfaee3
Documentation PoC with instructions and templates / based on John Ament initial work Project: http://git-wip-us.apache.org/repos/asf/deltaspike/repo Commit: http://git-wip-us.apache.org/repos/asf/deltaspike/commit/86fb1ce9 Tree: http://git-wip-us.apache.org/repos/asf/deltaspike/tree/86fb1ce9 Diff: http://git-wip-us.apache.org/repos/asf/deltaspike/diff/86fb1ce9 Branch: refs/heads/master Commit: 86fb1ce976358613be73d9920fbb26a5a1e3b299 Parents: 6b39550 Author: Rafael Benevides <rafab...@gmail.com> Authored: Wed Aug 27 18:03:28 2014 -0300 Committer: John D. Ament <johndam...@apache.org> Committed: Mon Sep 8 19:18:06 2014 -0400 ---------------------------------------------------------------------- documentation/README.md | 47 ++++++ .../content/container-control-test.adoc | 157 +++++++++++++++++++ documentation/pom.xml | 110 +++++++++++++ documentation/template/document.html.erb | 104 ++++++++++++ 4 files changed, 418 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/deltaspike/blob/86fb1ce9/documentation/README.md ---------------------------------------------------------------------- diff --git a/documentation/README.md b/documentation/README.md new file mode 100644 index 0000000..2b18089 --- /dev/null +++ b/documentation/README.md @@ -0,0 +1,47 @@ +title: Apache DeltaSpike + +Notice: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + . + http://www.apache.org/licenses/LICENSE-2.0 + . + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +DeltaSpike documentation +------------------------- + +DeltaSpike documentation uses [Asciidoc](http://www.methods.co.nz/asciidoc/). You're welcome to contribute. + +License +------- +Apache DeltaSpike is licensed under ALv2. +See the LICENSE file for the full license text. + +Publish procedure +----------------- + +To publish the documentation at [DeltaSpike Site](http://deltaspike.apache.org/) you have do the following steps: + +Put the following information in your ~/.m2/settings.xml file + + <server> + <id>deltaspike-site</id> + <username><YOUR_USERNAME></username> + <password><YOUR_PASSWORD></password> + </server> + +Then run: + + mvn site-deploy + +After log in to <https://cms.apache.org/deltaspike/publish> and click on the `Submit` button. http://git-wip-us.apache.org/repos/asf/deltaspike/blob/86fb1ce9/documentation/content/container-control-test.adoc ---------------------------------------------------------------------- diff --git a/documentation/content/container-control-test.adoc b/documentation/content/container-control-test.adoc new file mode 100644 index 0000000..fc420ed --- /dev/null +++ b/documentation/content/container-control-test.adoc @@ -0,0 +1,157 @@ += Container & Control + +:toc: + +== Introduction + +There are basically two parts: + + - The `CdiContainer` interface allows to boot and shutdown the CDI container in SE applications. + - The `ContextControl` interface allows to control the life-cycle of the built-in contexts of the CDI container. + +=== CdiContainer +You can use the `CdiContainerLoader` as a simple factory to gain access to the underlying `CdiContainer` implementation. This is of little interest for Java EE applications since the CDI Container +already gets properly booted and shut down by the Servlet container integration. + + +[source,java] +---- +// this will give you a CdiContainer for Weld or OWB, depending on the jar you added +CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer(); +// now we gonna boot the CDI container. This will trigger the classpath scan, etc +cdiContainer.boot(); +// and finally we like to start all built-in contexts +cdiContainer.getContextControl().startContexts(); +// now we can use CDI in our SE application. +// And there is not a single line of OWB or Weld specific code in your project! +// finally we gonna stop the container +cdiContainer.shutdown(); +---- + +=== ContextControl usage + +The `ContextControl` interface allows you to start and stop built-in standard Contexts like `@RequestScoped`, `@ConversationScoped`, `@SessionScoped`, etc. It is provided as `@Dependent` bean and can get injected in the classic CDI way. This is not only usable in Java SE projects but also very helpful in Servlets and Java EE containers. + +**Restarting the RequestContext in unit tests** + +In unit testing it can be necessary to test with attached and also with detached JPA entities. A very common approach for +JPA is the link: http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Web_Server/1.0/html/Hibernate_Entity_Manager_Reference_Guide/transactions.html[entitymanager-per-request approach^] +and thus have a producer method which creates a `@RequestScoped EntityManager`. Since a single unit test is usually +treated as one ârequestâ a problem arises detaching entities. + +Using ContextControl to detach entities: + +[source,java] +---- +@Test +public void testMyBusinessLogic() +{ + doSomeJpaStuff() + MyEntity me = em.find(...); + ContextControl ctxCtrl = BeanProvider.getContextualReference(ContextControl.class); + //stopping the request context will dispose the @RequestScoped EntityManager + ctxCtrl.stopContext(RequestScoped.class); + // and now immediately restart the context again + ctxCtrl.startContext(RequestScoped.class); + // the entity 'em' is now in a detached state! + doSomeStuffWithTheDetachedEntity(em); +} +---- + +Attaching a Request Context to a new thread in EE + +Accessing the `@RequestScoped` bean in a new thread will result in a `ContextNotActiveException`. The request-context usually gets started for a particular thread via a simple `ServletRequestListener`. So "no servlet-request" means that there is no Servlet-Context for the current (/new) Thread. +You might face such issues, if you would like to reuse business services in e.g. a Quartz Job. + +Controlling the request-context for a Quartz-Job: + +[source,java] +---- +public class CdiJob implements org.quartz.Job +{ + public void execute(JobExecutionContext context) throws JobExecutionException + { + ContextControl ctxCtrl = BeanProvider.getContextualReference(ContextControl.class); + //this will implicitly bind a new RequestContext to the current thread + ctxCtrl.startContext(RequestScoped.class); + try + { + doYourWork(); + } + finally + { + //stop the RequestContext to ensure that all request-scoped beans get cleaned up. + ctxCtrl.stopContext(RequestScoped.class); + } + } +} +---- + +=== Embedded Servlet Support + +Starting with 1.0.2, you can use DeltaSpike to power embedded Servlet runtimes. This work is done via Servlet Listeners. The configuration is specific to each container, below are some examples. + +The two main listeners are `CdiServletRequestListener` and `CdiServletContextListener`. `CdiServletRequestListener` is responsible for starting a `RequestContext` on each incoming request. In most containers this is all you need. For Tomcat specifically, you need to use `CdiServletContextListener` which registers the `CdiServletRequestListener`. + +The main usecase for this feature is for lightweight embedded runtimes, microservices. For each of these, it is assumed that you are using the following start up code somewhere: + +[source,java] +---- +CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer(); +cdiContainer.boot(); +cdiContainer.getContextControl().startContexts(); +---- + +==== Jetty +For Jetty, you need to add an `EventListener` which will be your `CdiServletRequestListener`. The object must be instantiated. This must be done before the server is started. + +[source,java] +---- +Server server = new Server(port); +ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS); +context.setContextPath("/"); +server.setHandler(context); +context.addEventListener(new CdiServletRequestListener()); +context.addServlet(new ServletHolder(new YourServlet()),"/*"); +server.start(); +---- + +==== Undertow +For Undertow, you register the `CdiServletRequestListener` via `ListenerInfo` by passing in the class to their builders. Then you add the `ListenerInfo` to your deployment before starting. + +[source,java] +---- +ServletInfo servletInfo = Servlets.servlet("YourServletName", YourServlet.class).setAsyncSupported(true) + .setLoadOnStartup(1).addMapping("/*"); +ListenerInfo listenerInfo = Servlets.listener(CdiServletRequestListener.class); // <1> +DeploymentInfo di = new DeploymentInfo() + .addListener(listenerInfo) // <2> + .setContextPath("/") + .addServlet(servletInfo).setDeploymentName("CdiSEServlet") + .setClassLoader(ClassLoader.getSystemClassLoader()); +DeploymentManager deploymentManager = Servlets.defaultContainer().addDeployment(di); +deploymentManager.deploy(); +Undertow server = Undertow.builder() + .addHttpListener(port, "localhost") + .setHandler(deploymentManager.start()) + .build(); +server.start(); +---- +<1> Register as a listener. +<2> Add to deployment + +==== Tomcat +For Tomcat, you need to register the `CdiServletContextListener` instead of the `CdiServletRequestListener`. It is added as an `ApplicationListener` by passing in the class name as a `String`. + +[source,java] +---- +Tomcat tomcat = new Tomcat(); +tomcat.setPort(port); +File base = new File("..."); +Context ctx = tomcat.addContext("/",base.getAbsolutePath()); +StandardContext standardContext = (StandardContext)ctx; +standardContext.addApplicationListener(CdiServletContextListener.class.getName()); +Wrapper wrapper = Tomcat.addServlet(ctx,"YourServlet",YourServlet.class.getName()); +wrapper.addMapping("/*"); +tomcat.start(); +---- \ No newline at end of file http://git-wip-us.apache.org/repos/asf/deltaspike/blob/86fb1ce9/documentation/pom.xml ---------------------------------------------------------------------- diff --git a/documentation/pom.xml b/documentation/pom.xml new file mode 100644 index 0000000..ba1ede0 --- /dev/null +++ b/documentation/pom.xml @@ -0,0 +1,110 @@ +<?xml version="1.0" encoding="UTF-8"?> +<project xmlns="http://maven.apache.org/POM/4.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd";> + <!-- Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with this + work for additional information regarding copyright ownership. The ASF licenses + this file to you under the Apache License, Version 2.0 (the "License"); you + may not use this file except in compliance with the License. You may obtain + a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless + required by applicable law or agreed to in writing, software distributed + under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES + OR CONDITIONS OF ANY KIND, either express or implied. See the License for + the specific language governing permissions and limitations under the License. --> + <modelVersion>4.0.0</modelVersion> + + <parent> + <groupId>org.apache</groupId> + <artifactId>apache</artifactId> + <version>11</version> + </parent> + + <!-- * Please do not use this pom for other deltaspike modules. * Instead + use the one from parent/pom.xml! * * This very pom.xml contains only the + basic build layout * and no build-rules at all. See parent/pom.xml for all + * the dependencyManagement and plugin configuration stuff. --> + <groupId>org.apache.deltaspike</groupId> + <artifactId>deltaspike-documentation</artifactId> + <version>1.0.3-SNAPSHOT</version> + <packaging>pom</packaging> + + <name>Apache DeltaSpike - Documentation</name> + <description> + Documentation of DeltaSpike project. + </description> + <url>http://deltaspike.apache.org</url> + + <properties> + <asciidoctor.version>0.1.4</asciidoctor.version> + <svn.scmPubUrl>https://svn.apache.org/repos/asf/deltaspike/site/trunk/content/documentation/</svn.scmPubUrl> + <svn.scmPubCheckoutDirectory>${project.build.directory}/co-site</svn.scmPubCheckoutDirectory> + </properties> + + <distributionManagement> + <site> + <id>apache.website</id> + <url>${svn.scmPubUrl}</url> + </site> + </distributionManagement> + + <build> + <plugins> + <plugin> + <groupId>org.asciidoctor</groupId> + <artifactId>asciidoctor-maven-plugin</artifactId> + <version>${asciidoctor.version}</version> + <executions> + <execution> + <id>output-html</id> + <phase>site</phase> + <goals> + <goal>process-asciidoc</goal> + </goals> + </execution> + </executions> + <configuration> + <sourceDirectory>content</sourceDirectory> + <outputDirectory>${project.build.directory}/site</outputDirectory> + <sourceHighlighter>coderay</sourceHighlighter> + <backend>html</backend> + <templateDir>template</templateDir> + <eruby>erb</eruby> + <attributes> + <toc>true</toc> + </attributes> + </configuration> + </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-scm-publish-plugin</artifactId> + <version>1.1</version> + <executions> + <execution> + <id>scm-publish</id> + <phase>site-deploy</phase> + <!-- deploy site with maven-scm-publish-plugin --> + <goals> + <goal>publish-scm</goal> + </goals> + </execution> + </executions> + <configuration> + <content>${project.reporting.outputDirectory}</content> + <pubScmUrl>scm:svn:${svn.scmPubUrl}</pubScmUrl> + <tryUpdate>true</tryUpdate> + <checkoutDirectory>${svn.scmPubCheckoutDirectory}</checkoutDirectory> + <serverId>deltaspike-site</serverId> + </configuration> + </plugin> + <!-- this is a hack, to make site not really run. --> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-site-plugin</artifactId> + <configuration> + <skip>true</skip> + <skipDeploy>true</skipDeploy> + </configuration> + </plugin> + </plugins> + </build> +</project> http://git-wip-us.apache.org/repos/asf/deltaspike/blob/86fb1ce9/documentation/template/document.html.erb ---------------------------------------------------------------------- diff --git a/documentation/template/document.html.erb b/documentation/template/document.html.erb new file mode 100644 index 0000000..781b518 --- /dev/null +++ b/documentation/template/document.html.erb @@ -0,0 +1,104 @@ +<%#encoding:UTF-8%><!DOCTYPE html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> + +<meta charset="utf-8"> +<meta name="viewport" content="width=device-width, initial-scale=1.0"> +<meta name="description" content="deltaspike-generate-pages"> +<meta name="author" content="chm"> + +<title><%= document.name %></title> + +<!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> + +<!-- Styles --> + +<link href="http://deltaspike.apache.org/resources/css/bootstrap.css"; rel="stylesheet"> +<link href="http://deltaspike.apache.org/resources/css/bootstrap-responsive.css"; rel="stylesheet"> + +<style type="text/css"> +<%= ::Asciidoctor::HTML5.default_coderay_stylesheet %> +body { + padding-top: 60px; + padding-bottom: 40px; +} +</style> +<script type="text/javascript"> + + var _gaq = _gaq || []; + _gaq.push(['_setAccount', 'UA-36103647-1']); + _gaq.push(['_trackPageview']); + + (function() { + var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; + ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; + var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); + })(); + + </script> +</head> + +<body> + + <div class="navbar navbar-fixed-top"> + <div class="navbar-inner"> + <div class="container"> + <a class="btn btn-navbar" data-toggle="collapse" + data-target=".nav-collapse"> <span class="icon-bar"></span> <span + class="icon-bar"></span> <span class="icon-bar"></span> + </a> <a class="brand logocolor" + href="http://deltaspike.apache.org/index.html";>Apache + DeltaSpike</a> + <div class="nav-collapse"> + <ul class="nav"> + <li class="active"><a + href="http://deltaspike.apache.org/index.html";>Home</a></li> + <li><a href="http://deltaspike.apache.org/documentation";>Documentation</a></li> + <li><a href="http://deltaspike.apache.org/source.html";>Source</a></li> + <li><a href="http://deltaspike.apache.org/download.html";>Download</a></li> + <li><a href="http://deltaspike.apache.org/community.html";>Community</a></li> + <!-- <li><a href="./support.html">Support</a></li> --> + <li><a href="http://deltaspike.apache.org/news.html";>News</a></li> + <li><a + href="http://deltaspike.apache.org/migration-guide.html";>Migration</a></li> + </ul> + </div> + <!--/.nav-collapse --> + <form id="search-form" action="http://www.google.com/search"; + method="get" class="navbar-search pull-right"> + <input value="deltaspike.apache.org" name="sitesearch" + type="hidden"> <input class="search-query" name="q" + id="query" type="text"> + </form> + </div> + </div> + </div> + + <div class="container"> + <div class="row"> + <div class="span12"> + <div class="page-title"> + <h1><%= document.name %></h1> + </div> + + <div id="toc" class="<%= attr 'toc-class', 'toc' %>"> + <%= ::Asciidoctor::HTML5::DocumentTemplate.outline(self, (attr :toclevels, 3).to_i) %> + <hr> + + <%= document.content %> + </div> + + <hr> + + <footer> + <p>Copyright © 2011-2014 The Apache Software Foundation, + Licensed under the Apache License, Version 2.0.</p> + <p>Apache and the Apache feather logo are trademarks of The + Apache Software Foundation.</p> + </footer> + + </div> + <!-- /.container --> + +</body> +</html> \ No newline at end of file
