hbase-archetypes/README.md

   1 <!---
   2 Licensed to the Apache Software Foundation (ASF) under one
   3 or more contributor license agreements.  See the NOTICE file
   4 distributed with this work for additional information
   5 regarding copyright ownership.  The ASF licenses this file
   6 to you under the Apache License, Version 2.0 (the
   7 "License"); you may not use this file except in compliance
   8 with the License.  You may obtain a copy of the License at
   9
  10   http://www.apache.org/licenses/LICENSE-2.0
  11
  12 Unless required by applicable law or agreed to in writing,
  13 software distributed under the License is distributed on an
  14 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  15 KIND, either express or implied.  See the License for the
  16 specific language governing permissions and limitations
  17 under the License.
  18 -->
  19
  20 #hbase-archetypes
  21
  22 ##Overview
  23 The hbase-archetypes subproject of hbase provides an infrastructure for
  24 creation and maintenance of Maven archetypes<sup id="a1">[1](#f1)</sup>
  25 pertinent to HBase. Upon deployment to the archetype
  26 catalog<sup id="a2">[2](#f2)</sup> of the central Maven
  27 repository<sup id="a3">[3](#f3)</sup>, these archetypes may be used by
  28 end-user developers to autogenerate completely configured Maven projects
  29 (including fully-functioning sample code) through invocation of the
  30 `archetype:generate` goal of the
  31 maven-archetype-plugin<sup id="a4">[4](#f4)</sup>.
  32
  33 ##Notes for contributors and committers to the HBase project
  34
  35 ####The structure of hbase-archetypes
  36 The hbase-archetypes project contains a separate subproject for each archetype.
  37 The top level components of such a subproject comprise a complete, standalone
  38 exemplar Maven project containing:
  39
  40 - a `src` directory with sample, fully-functioning code in the `./main` and
  41 `./test` subdirectories,
  42 - a `pom.xml` file defining all required dependencies, and
  43 - any additional resources required by the exemplar project.
  44
  45 For example, the components of the hbase-client-project consist of (a) sample
  46 code `./src/main/.../HelloHBase.java` and `./src/test/.../TestHelloHBase.java`,
  47 (b) a `pom.xml` file establishing dependency upon hbase-client and test-scope
  48 dependency upon hbase-testing-util, and (c) a `log4j.properties` resource file.
  49
  50 ####How archetypes are created during the hbase install process
  51 During the `mvn install` process, all standalone exemplar projects in the
  52 `hbase-archetypes` subdirectory are first packaged/tested/installed, and then
  53 the following steps are executed in `hbase-archetypes/hbase-archetype-builder`
  54 (via the `pom.xml`, bash scripts, and xsl templates in that subdirectory):
  55
  56 1. For each exemplar project, resources are copied (via
  57 maven-resources-plugin) and transformed (via xml-maven-plugin xslt
  58 functionality) to the exemplar project's `./target/build-archetype`
  59 subdirectory<sup id="a5">[5](#f5)</sup>.
  60 2. The script `createArchetypes.sh` is executed to invoke the
  61 maven-archetype-plugin's `create-from-project` goal within each exemplar
  62 project's `./target/build-archetype` subdirectory. For each exemplar
  63 project, this creates a corresponding Maven archetype in the
  64 `./target/build-archetype/target/generate-sources/archetype` subdirectory.
  65 (Note that this step always issues two platform-encoding warnings per
  66 archetype, due to hard-wired behavior of the
  67 maven-archetype-plugin<sup id="a6">[6](#f6)</sup>.)
  68 3. The `pom.xml` file of each newly-created archetype is copied (via
  69 maven-resources-plugin) and transformed (via xml-maven-plugin xslt
  70 functionality)<sup id="a7">[7](#f7)</sup>.
  71 4. The script `installArchetypes.sh` is executed to install each archetype
  72 into the local Maven repository, ready for deployment to the central Maven
  73 repository. (Note that installation of an archetype automatically includes
  74 invocation of integration-testing prior to install, which performs a test
  75 generation of a project from the archetype.)
  76
  77 ####How to add a new archetype to the hbase-archetypes collection
  78 1. Create a new subdirectory in `hbase-archetypes`, populated with a
  79 completely configured Maven project, which will serve as the exemplar project
  80 of the new archetype. (It may be most straightforward to simply copy the `src`
  81 and `pom.xml` components from one of the existing exemplar projects, replace
  82 the `src/main` and `src/test` code, and modify the `pom.xml` file's
  83 `<dependencies>`, `<artifactId>`,` <name>`, and `<description>` elements.)
  84 2. Modify the `hbase-archetypes/pom.xml` file: add a new `<module>` subelement
  85 to the `<modules>` element, with the new exemplar project's subdirectory name
  86 as its value.
  87 3. Modify the `hbase-archetype-builder/pom.xml` file: (a) add a new `<*.dir>`
  88 subelement to the `<properties>` element, with the new exemplar project's
  89 subdirectory name as its value, and (b) add appropriate `<execution>`
  90 elements and `<transformationSet>` elements within the `<plugin>` elements
  91 (using the existing entries from already-existing exemplar projects as a guide).
  92 4. Add appropriate entries for the new exemplar project to the
  93 `createArchetypes.sh` and `installArchetypes.sh` scripts in the
  94 `hbase-archetype-builder` subdirectory (using the existing entries as a guide).
  95
  96 ####How to do additional testing/inspection of an archetype in this collection
  97 Although integration-testing (which is automatically performed for each
  98 archetype during the install process) already performs test generation of a
  99 project from an archetype, it may often be advisable to do further manual
 100 testing of a newly built and installed archetype, particularly to examine and
 101 test a project generated from the archetype (emulating the end-user experience
 102 of utilizing the archetype). Upon completion of the install process outlined
 103 above, all archetypes will have been installed in the local Maven repository
 104 and can be tested locally by executing the following:
 105     `mvn archetype:generate -DarchetypeCatalog=local`
 106 This displays a numbered list of all locally-installed archetypes for the user
 107 to choose from for generation of a new Maven project.
 108
 109 ##Footnotes:
 110 <b id="f1">1</b> -- [Maven Archetype
 111 ](http://maven.apache.org/archetype/index.html) ("About" page).
 112 -- [↩](#a1)
 113
 114 <b id="f2">2</b> -- [Maven Archetype Catalog
 115 ](http://repo1.maven.org/maven2/archetype-catalog.xml) (4MB+ xml file).
 116 -- [↩](#a2)
 117
 118 <b id="f3">3</b> -- [Maven Central Repository](http://search.maven.org/)
 119 (search engine).
 120 -- [↩](#a3)
 121
 122 <b id="f4">4</b> -- [Maven Archetype Plugin - archetype:generate
 123 ](http://maven.apache.org/archetype/maven-archetype-plugin/generate-mojo.html).
 124 -- [↩](#a4)
 125
 126 <b id="f5">5</b> -- Prior to archetype creation, each exemplar project's
 127     `pom.xml` is transformed as follows to make it into a standalone project:
 128     RESOURCE FILTERING (a) replaces `${project.version}` with the literal value
 129     of the current project.version and (b) replaces `${compileSource}` with the
 130     literal value of the version of Java that is being used for compilation;
 131     XSLT TRANSFORMATION (a) copies `<groupId>` and `<version>` subelements of
 132     `<parent>` to make them child elements of the root element, and (b) removes
 133     the `<parent>` and `<description>` elements.
 134     -- [↩](#a5)
 135
 136 <b id="f6">6</b> -- For an explanation of the platform-encoding warning issued
 137     during maven-archetype-plugin processing, see the first answer to [this
 138     stackoverflow posting](http://stackoverflow.com/a/24161287/4112172).
 139     -- [↩](#a6)
 140
 141 <b id="f7">7</b> -- Prior to archetype installation, each archetype's `pom.xml`
 142     is transformed as follows: a `<project.build.sourceEncoding>` subelement
 143     with value 'UTF-8' is added to the `<properties>` element. This prevents
 144     platform-encoding warnings from being issued when an end-user generates
 145     a project from the archetype.
 146     -- [↩](#a7)