DELTASPIKE-690: General text imporvements to 'Get Started' pages
Project: http://git-wip-us.apache.org/repos/asf/deltaspike/repo Commit: http://git-wip-us.apache.org/repos/asf/deltaspike/commit/427897c3 Tree: http://git-wip-us.apache.org/repos/asf/deltaspike/tree/427897c3 Diff: http://git-wip-us.apache.org/repos/asf/deltaspike/diff/427897c3 Branch: refs/heads/master Commit: 427897c3ab4f2208ca11f924d747df18883480f1 Parents: 0a034dd Author: michellemurray <[email protected]> Authored: Tue Dec 2 13:49:52 2014 +1000 Committer: Rafael Benevides <[email protected]> Committed: Mon Dec 15 20:24:45 2014 -0200 ---------------------------------------------------------------------- documentation/src/main/asciidoc/cdiimp.adoc | 47 +++++++++------------ documentation/src/main/asciidoc/configure.adoc | 12 +++--- documentation/src/main/asciidoc/examples.adoc | 32 +------------- documentation/src/main/asciidoc/index.adoc | 4 +- 4 files changed, 30 insertions(+), 65 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/deltaspike/blob/427897c3/documentation/src/main/asciidoc/cdiimp.adoc ---------------------------------------------------------------------- diff --git a/documentation/src/main/asciidoc/cdiimp.adoc b/documentation/src/main/asciidoc/cdiimp.adoc index 6d6acbd..9b63d6f 100644 --- a/documentation/src/main/asciidoc/cdiimp.adoc +++ b/documentation/src/main/asciidoc/cdiimp.adoc @@ -4,7 +4,7 @@ :toc: -DeltaSpike requires a CDI implementation to be available in the Java environment that your projects are deployed to. The implementation provides the CDI essentials, managing dependency injection and contextual lifecycles. link:http://weld.cdi-spec.org/[JBoss Weld] and link:http://openwebbeans.apache.org/[Apache OpenWebBeans (OWB)] are two widely used CDI implementations. Dependent on the Java environment you choose, some setup may be necessary as detailed here. +DeltaSpike requires a CDI implementation to be available in the Java environment where your projects are deployed. The implementation provides the CDI essentials, managing dependency injection and contextual lifecycles. link:http://weld.cdi-spec.org/[JBoss Weld] and link:http://openwebbeans.apache.org/[Apache OpenWebBeans (OWB)] are two widely used CDI implementations. Dependent on the Java environment you choose, some setup may be necessary as detailed here. == Java EE6+ Containers CDI is part of Java EE6 and later so CDI implementations are included as standard in Java EE6+ compliant environments. There is no additional CDI configuration needed besides including the CDI-obligatory `beans.xml` file in your project. @@ -23,7 +23,9 @@ DeltaSpike provides a dedicated Container Control module to enable applications Instructions are provided here for adding the required resources to both Maven-based and Maven-independent projects and subsequently booting the CDI container from your project source code. -=== Declare Dependencies for Maven-based Projects +=== 1. Declare CDI Dependencies + +==== Option A: Declare Dependencies for Maven-based Projects For Maven-based projects, the Container Control module is available in Maven Central together with the other DeltaSpike modules. You must configure your project to use the DeltaSpike Container Control API and one of the CDI container-specific modules. . Open the project `pom.xml` file for editing @@ -41,10 +43,9 @@ For Maven-based projects, the Container Control module is available in Maven Cen + . Add CDI container dependencies for one of the container options listed here -==== Option A: For JBoss Weld - -. Open the project `pom.xml` file for editing -. Add the JBoss Weld version to the list of properties, replacing the version as desired ++ +.For JBoss Weld +a. Add the JBoss Weld version to the list of properties, replacing the version as desired + [source,xml] ---- @@ -53,7 +54,7 @@ For Maven-based projects, the Container Control module is available in Maven Cen </properties> ---- + -. Add the JBoss Weld dependency to the list of dependencies +b. Add the JBoss Weld dependency to the list of dependencies + [source,xml] ---- @@ -65,7 +66,7 @@ For Maven-based projects, the Container Control module is available in Maven Cen </dependency> ---- + -. Add the DeltaSpike Weld-specific Container Control module to the list of dependencies +c. Add the DeltaSpike Weld-specific Container Control module to the list of dependencies + [source,xml] ---- @@ -76,18 +77,10 @@ For Maven-based projects, the Container Control module is available in Maven Cen <scope>runtime</scope> </dependency> ---- -+ -. Save the `pom.xml` file changes -. Download all required dependencies -+ ----- -mvn clean install ----- - -==== Option B: For Apache OpenWebBeans -. Open the project `pom.xml` file for editing -. Add the Apache OpenWebBeans version to the list of properties, replacing the version as desired ++ +.For Apache OpenWebBeans +a. Add the Apache OpenWebBeans version to the list of properties, replacing the version as desired + [source,xml] ---- @@ -96,7 +89,7 @@ mvn clean install </properties> ---- + -. Add the Apache OpenWebBeans dependencies to the list of dependencies +b. Add the Apache OpenWebBeans dependencies to the list of dependencies + [source,xml] ---- @@ -115,7 +108,7 @@ mvn clean install </dependency> ---- + -. Add the DeltaSpike Apache OpenWebBeans-specific Container Control module to the list of dependencies +c. Add the DeltaSpike Apache OpenWebBeans-specific Container Control module to the list of dependencies + [source,xml] ---- @@ -126,7 +119,7 @@ mvn clean install <scope>runtime</scope> </dependency> ---- -+ + . Save the `pom.xml` file changes . Download all required dependencies + @@ -134,12 +127,12 @@ mvn clean install mvn clean install ---- -=== Declare Dependencies for Maven-independent Projects +==== Option B: Declare Dependencies for Maven-independent Projects For Maven-independent projects, the Container Control module is distributed together with the other DeltaSpike modules in `distribution-fill-<version>.zip`. You must add two of the files from the `cdictrl` directory to your project, namely `deltaspike-cdictrl-api.jar` and the .jar file that corresponds to the CDI container you have chosen. Add these files to the project `WEB-INF/lib` or `EAR/lib` directory for .war and .ear projects respectively. -=== Start the CDI Container from Your Project +=== 2. Start the CDI Container from Your Project To start a CDI container in your application, you must instantiate a `CdiContainer` object and call the `#boot` method. When `#boot` is called, the `CdiContainer` scans CDI-enabled -archives for beans and CDI extensions. An example is given in the code snippet here. Before the application exits, `#shutdown` must be called to correctly destroy all beans. +archives for beans and CDI extensions. Before the application exits, `#shutdown` must be called to correctly destroy all beans. An example is given in the code snippet here. [source,java] ---- @@ -174,7 +167,7 @@ public class MainApp { CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer(); cdiContainer.boot(); - // Starting the application-context allows to use @ApplicationScoped beans + // Starting the application-context enables use of @ApplicationScoped beans ContextControl contextControl = cdiContainer.getContextControl(); contextControl.startContext(ApplicationScoped.class); @@ -185,7 +178,7 @@ public class MainApp { } ---- -To resolve project beans, you can use the DeltaSpike `BeanProvider` class. Whether `EchoService` is a concrete implementation or just an interface depends on the application. In the case that it is an interface, the corresponding implementation is resolved. The resolved bean is a standard CDI bean and it can be used for all CDI concepts, such as @Inject, in the class without further uses of `BeanProvider`. An example of resolving the bean without qualifiers is given in the code snippet here. +To resolve project beans, you can use the DeltaSpike `BeanProvider` class. Whether `EchoService` is a concrete implementation or just an interface depends on the application. In the case that it is an interface, the corresponding implementation is resolved. The resolved bean is a standard CDI bean and it can be used for all CDI concepts, such as `@Inject`, in the class without further uses of `BeanProvider`. An example of resolving the bean without qualifiers is given in the code snippet here. [source,java] ---- http://git-wip-us.apache.org/repos/asf/deltaspike/blob/427897c3/documentation/src/main/asciidoc/configure.adoc ---------------------------------------------------------------------- diff --git a/documentation/src/main/asciidoc/configure.adoc b/documentation/src/main/asciidoc/configure.adoc index df99230..3c8b4ff 100644 --- a/documentation/src/main/asciidoc/configure.adoc +++ b/documentation/src/main/asciidoc/configure.adoc @@ -6,9 +6,9 @@ DeltaSpike is available for use in Maven-based and Maven-independent projects. Instructions are given here for obtaining released final versions of DeltaSpike for both approaches. -**Note:** You can also opt to use the lastest DeltaSpike snapshots; for more information, see <<snapshots#,Test Snapshots>>. +**Note:** You can also opt to use the lastest DeltaSpike snapshots; for more information, see <<snapshots#,Use DeltaSpike Snapshots>>. -== Configure DeltaSpike in Maven-based Projects +== Option A: Configure DeltaSpike in Maven-based Projects DeltaSpike released versions are available from the Maven Central repository for use in Maven-based projects. This means that you do not need to modify your Maven configuration `settings.xml` file; when building projects, Maven automatically searches the online Maven Central repository for project dependencies and downloads sources to your local Maven repository. To begin use the DeltaSpike releases from Maven Central, you simply need to configure the project `pom.xml` file for each project with information about the release version and modules you want to use. At a minimum, you must add the DeltaSpike Core module, which provides the DeltaSpike API and utility classes. @@ -57,7 +57,7 @@ For instructions on adding the optional DeltaSpike modules, see the relevant mod * <<servlet#,Servlet>> * <<test-control#,Test-Control>> -== Configure DeltaSpike in Maven-independent Projects +== Option B: Configure DeltaSpike in Maven-independent Projects Deltaspike is provided as a set of downloadable .jar files for projects not utilizing the Maven build system. Alternatively, you can build the DeltaSpike .jar files from source; for instructions, see <<build#,Build DeltaSpike from Source>>. In both cases, you must add the DeltaSpike .jar files directly to your projects. To use DeltaSpike without Maven from the downloadable .jar files, complete the following steps: @@ -71,8 +71,8 @@ $ unzip distribution-full-<version>.zip ---- + . Add the source to your project - .. For .war projects, copy the .jar files to `WEB-INF/lib` directory - .. For .ear projects, copy the .jar files to `EAR/lib directory` and add the following to `META-INF/application.xml`: +a. For .war projects, copy the .jar files to the `WEB-INF/lib` directory +b. For .ear projects, copy the .jar files to the `EAR/lib directory` and add the following to `META-INF/application.xml`: + [source,xml] ---- @@ -80,6 +80,6 @@ $ unzip distribution-full-<version>.zip ---- == Next -* To check whether your Java envrionment needs any additional CDI-specific configuration, see <<cdiimp#,Enable CDI For Your Java Environment>>. +* To check whether your Java environment needs any additional CDI-specific configuration, see <<cdiimp#,Enable CDI For Your Java Environment>>. * To see ready-to-deploy example DeltaSpike applications, see <<examples#,See DeltaSpike in Action>>. * To understand how the various DeltaSpike modules can enhance and extend your applications, see the individual module pages. http://git-wip-us.apache.org/repos/asf/deltaspike/blob/427897c3/documentation/src/main/asciidoc/examples.adoc ---------------------------------------------------------------------- diff --git a/documentation/src/main/asciidoc/examples.adoc b/documentation/src/main/asciidoc/examples.adoc index 2ba01eb..aaeb557 100644 --- a/documentation/src/main/asciidoc/examples.adoc +++ b/documentation/src/main/asciidoc/examples.adoc @@ -4,7 +4,7 @@ :toc: -A collection of ready-to-build Maven-based projects are provided to demonstrate the inclusion of DeltaSpike in applications. Each example showcases a different DeltaSpike feature and explores the mechanics of DeltaSpike implementation. You can use these examples to see DeltaSpike in action and learn how to add these capabilities to your own projects. The Maven-based project examples are available in `deltaspike-project-<version>-source-release.zip` and each is briefly outlined here. +A collection of ready-to-build Maven-based projects are provided to demonstrate the inclusion of DeltaSpike in applications. Each example showcases a different DeltaSpike feature and explores the mechanics of DeltaSpike implementation. You can use these examples to see DeltaSpike in action and learn how to add these capabilities to your own projects. The Maven-based project examples are available in `deltaspike-project-<version>-source-release.zip`. To begin using the projects, complete the following steps: @@ -22,32 +22,4 @@ $ unzip deltaspike-project-<version>-source-release.zip ---- $ cd /path/to/deltaspike-project-<version>/examples $ mvn clean package ----- - -== jse-examples -**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question: - -* What is the purpose of the example (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)? -* When would the user use this example (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)? -* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)? - -== jsf-examples -**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question: - -* What is the purpose of the example (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)? -* When would the user use this example (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)? -* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)? - -== jsf-playground -**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question: - -* What is the purpose of the example (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)? -* When would the user use this example (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)? -* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)? - -== scheduler-playground -**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question: - -* What is the purpose of the example (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)? -* When would the user use this example (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)? -* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)? \ No newline at end of file +---- \ No newline at end of file http://git-wip-us.apache.org/repos/asf/deltaspike/blob/427897c3/documentation/src/main/asciidoc/index.adoc ---------------------------------------------------------------------- diff --git a/documentation/src/main/asciidoc/index.adoc b/documentation/src/main/asciidoc/index.adoc index eec24a1..c83cfc9 100644 --- a/documentation/src/main/asciidoc/index.adoc +++ b/documentation/src/main/asciidoc/index.adoc @@ -2,12 +2,12 @@ :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. -* Getting Started +* Get Started ** <<overview#,Overview of DeltaSpike>> ** <<configure#,Configure DeltaSpike in Your Projects>> ** <<cdiimp#,Enable CDI For Your Java Environment>> ** <<examples#,See DeltaSpike in Action>> -* Using Individual Modules +* Use Individual Modules ** <<core#,Core>> ** <<bean-validation#,Bean Validation>> ** <<container-control#,Container Control>>
