You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by aa...@apache.org on 2019/11/06 09:07:59 UTC
[cayenne] 01/02: Docs: moving tools into a separate chapter.
Modeler is the way to go since 4.1. Simplifying "including" chapter to
avoid uneeded confusion
This is an automated email from the ASF dual-hosted git repository.
aadamchik pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cayenne.git
commit 29bea2eee432abba5391d521b1972d01c0a69b9b
Author: Andrus Adamchik <an...@objectstyle.com>
AuthorDate: Wed Nov 6 11:27:13 2019 +0300
Docs: moving tools into a separate chapter. Modeler is the way to go since 4.1.
Simplifying "including" chapter to avoid uneeded confusion
---
.../asciidoc/_cayenne-guide/part1/modeler.adoc | 1 +
.../src/docs/asciidoc/_cayenne-guide/part2.adoc | 2 +-
.../asciidoc/_cayenne-guide/part2/including.adoc | 666 +--------------------
.../{listOfTables.adoc => part6.adoc} | 27 +-
.../asciidoc/_cayenne-guide/part6/ant-tasks.adoc | 59 ++
.../_cayenne-guide/part6/gradle-plugin.adoc | 178 ++++++
.../including.adoc => part6/maven-plugin.adoc} | 452 ++++----------
.../src/docs/asciidoc/cayenne-guide.adoc | 4 +-
8 files changed, 362 insertions(+), 1027 deletions(-)
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/modeler.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/modeler.adoc
index db9da95..a6ecf98 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/modeler.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/modeler.adoc
@@ -12,6 +12,7 @@
// the specific language governing permissions and limitations under the
// License.
+[#cayenne-modeler]
=== CayenneModeler Application
==== Reverse Engineering Database
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2.adoc
index 696fb15..bd1ac82 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2.adoc
@@ -30,4 +30,4 @@ include::part2/lifecycle.adoc[]
include::part2/tuning.adoc[]
-include::part2/customize.adoc[]
\ No newline at end of file
+include::part2/customize.adoc[]
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc
index b168417..947d2df 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc
@@ -5,7 +5,7 @@
// 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
//
-// https://www.apache.org/licenses/LICENSE-2.0 Unless required by
+// 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
@@ -14,28 +14,12 @@
include::../var.adoc[]
-[[including-cayenne-in-project]]
+[#including-cayenne-in-project]
=== Including Cayenne in a Project
-==== Jar Files
+==== Maven
-This is an overview of Cayenne jars that is agnostic of the build tool used. The following are the important libraries:
-
-- `cayenne-di-{version}.jar` - Cayenne dependency injection (DI) container library. All applications will require this file.
-
-- `cayenne-server-{version}.jar` - contains main Cayenne runtime (adapters, DB access classes, etc.). Most applications will require this file.
-
-- Other cayenne-* jars - various Cayenne tools extensions.
-
-==== Dependencies
-
-With modern build tools like Maven and Gradle, you should not worry about tracking dependencies. If you have one of those, you can skip this section and go straight to the Maven section below. However if your environment requires manual dependency resolution (like Ant), the distribution provides all of Cayenne jars plus a minimal set of third-party dependencies to get you started in a default configuration. Check lib and `lib/third-party` folders for those.
-
-Dependencies for non-standard configurations will need to be figured out by the users on their own. Check `pom.xml` files of the corresponding Cayenne modules in one of the searchable Maven archives out there to get an idea of those dependencies (e.g. http://search.maven.org).
-
-==== Maven Projects
-
-If you are using Maven, you won't have to deal with figuring out the dependencies. You can simply include cayenne-server artifact in your POM:
+To add Cayenne to your Maven project, include `cayenne-server` in your POM:
[source,xml,subs="verbatim,attributes"]
----
@@ -46,649 +30,17 @@ If you are using Maven, you won't have to deal with figuring out the dependencie
</dependency>
----
-Additionally Cayenne provides a Maven plugin with a set of goals to perform various project tasks, such as synching generated Java classes with the mapping, described in the following subsection. The full plugin name is `org.apache.cayenne.plugins:cayenne-maven-plugin`.
-
-[[cgen]]
-===== cgen
-
-`cgen` is a `cayenne-maven-plugin` goal that generates and maintains source (.java) files of persistent objects based on a DataMap. By default, it is bound to the generate-sources phase. If "makePairs" is set to "true" (which is the recommended default), this task will generate a pair of classes (superclass/subclass) for each ObjEntity in the DataMap. Superclasses should not be changed manually, since they are always overwritten. Subclasses are never overwritten and may be later customiz [...]
-
-By creating custom templates, you can use cgen to generate other output (such as web pages, reports, specialized code templates) based on DataMap information.
-
-[#tablecgen.table.table-bordered]
-.cgen required parameters
-[cols="1,1,4"]
-|===
-|Name |Type|Description
-
-.^|map
-.^|File
-a|DataMap XML file which serves as a source of metadata for class generation. E.g.
-[source]
-----
-${project.basedir}/src/main/resources/my.map.xml
-----
-|===
-
-
-[#cgenOptional.table.table-bordered]
-.cgen optional parameters
-[cols="2,1,5"]
-|===
-|Name |Type|Description
-
-.^|additionalMaps
-.^|File
-.^|A directory that contains additional DataMap XML files that may be needed to resolve cross-DataMap relationships for the the main DataMap, for which class generation occurs.
-
-.^|client
-.^|boolean
-.^|Whether we are generating classes for the client tier in a Remote Object Persistence application. "False" by default.
-
-.^|destDir
-.^|File
-.^|Root destination directory for Java classes (ignoring their package names). The default is "src/main/java".
-
-.^|embeddableTemplate
-.^|String
-.^|Location of a custom Velocity template file for Embeddable class generation. If omitted, default template is used.
-
-.^|embeddableSuperTemplate
-.^|String
-.^|Location of a custom Velocity template file for Embeddable superclass generation. Ignored unless "makepairs" set to "true". If omitted, default template is used.
-
-.^|encoding
-.^|String
-.^|Generated files encoding if different from the default on current platform. Target encoding must be supported by the JVM running the build. Standard encodings supported by Java on all platforms are US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16. See javadocs for java.nio.charset.Charset for more information.
-
-.^|excludeEntities
-.^|String
-.^|A comma-separated list of ObjEntity patterns (expressed as a perl5 regex) to exclude from template generation. By default none of the DataMap entities are excluded.
-
-.^|includeEntities
-.^|String
-.^|A comma-separated list of ObjEntity patterns (expressed as a perl5 regex) to include from template generation. By default all DataMap entities are included.
-
-.^|makePairs
-.^|boolean
-.^|If "true" (a recommended default), will generate subclass/superclass pairs, with all generated code placed in superclass.
-
-.^|mode
-.^|String
-.^|Specifies class generator iteration target. There are three possible values: "entity" (default), "datamap", "all". "entity" performs one generator iteration for each included ObjEntity, applying either standard to custom entity templates. "datamap" performs a single iteration, applying DataMap templates. "All" is a combination of entity and datamap.
-
-.^|overwrite
-.^|boolean
-.^|Only has effect when "makePairs" is set to "false". If "overwrite" is "true", will overwrite older versions of generated classes.
-
-.^|superPkg
-.^|String
-.^|Java package name of all generated superclasses. If omitted, each superclass will be placed in the subpackage of its subclass called "auto". Doesn't have any effect if either "makepairs" or "usePkgPath" are false (both are true by default).
-
-.^|superTemplate
-.^|String
-.^|Location of a custom Velocity template file for ObjEntity superclass generation. Only has effect if "makepairs" set to "true". If omitted, default template is used.
-
-.^|template
-.^|String
-.^|Location of a custom Velocity template file for ObjEntity class generation. If omitted, default template is used.
-
-.^|usePkgPath
-.^|boolean
-.^|If set to "true" (default), a directory tree will be generated in "destDir" corresponding to the class package structure, if set to "false", classes will be generated in "destDir" ignoring their package.
-
-.^|createPropertyNames
-.^|boolean
-.^|If set to "true", will generate String Property names. Default is "false"
-
-.^|force
-.^|boolean
-.^|If set to "true", will force run from maven/gradle.
-
-.^|createPKProperties
-.^|boolean
-.^|If set to "true", will generate PK attributes as Properties. Default is "false".
-|===
-
-Example - a typical class generation scenario, where pairs of classes are generated with default Maven source destination and superclass package:
-
-[source,xml,subs="verbatim,attributes"]
-----
-<plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>cayenne-maven-plugin</artifactId>
- <version>{project-version}</version>
-
- <configuration>
- <map>${project.basedir}/src/main/resources/my.map.xml</map>
- </configuration>
-
- <executions>
- <execution>
- <goals>
- <goal>cgen</goal>
- </goals>
- </execution>
- </executions>
-</plugin>
-----
-
-===== cdbgen
-
-`cdbgen` is a `cayenne-maven-plugin` goal that drops and/or generates tables in a database on Cayenne DataMap. By default, it is bound to the pre-integration-test phase.
-
-[#cdbgenTable.table.table-bordered]
-.cdbgen required parameters
-[cols="1,1,4"]
-|===
-|Name |Type|Description
-
-.^|map
-.^|File
-a|DataMap XML file which serves as a source of metadata for class generation. E.g.
-[source]
-----
-${project.basedir}/src/main/resources/my.map.xml
-----
-
-.^|dataSource
-.^|XML
-.^|An object that contains Data Source parameters
-|===
-
-
-[#dataSourceParameteres.table.table-bordered]
-.<dataSource> parameters
-[cols="2,1,2,5"]
-|===
-|Name |Type |Required |Description
-
-.^|driver
-.^|String
-.^|Yes
-.^|A class of JDBC driver to use for the target database.
-
-.^|url
-.^|String
-.^|Yes
-.^|JDBC URL of a target database.
-
-.^|username
-.^|String
-.^|No
-.^|Database user name.
-
-.^|password
-.^|String
-.^|No
-.^|Database user password.
-|===
-
-[#cdbgenOptionl.table.table-bordered]
-.cdbgen optional parameters
-[cols="1,1,4"]
-|===
-|Name |Type|Description
-
-.^|adapter
-.^|String
-.^|Java class name implementing org.apache.cayenne.dba.DbAdapter. While this attribute is optional (a generic JdbcAdapter is used if not set), it is highly recommended to specify correct target adapter.
-
-
-.^|createFK
-.^|boolean
-.^|Indicates whether cdbgen should create foreign key constraints. Default is "true".
-
-.^|createPK
-.^|boolean
-.^|Indicates whether cdbgen should create Cayenne-specific auto PK objects. Default is "true".
-
-.^|createTables
-.^|boolean
-.^|Indicates whether cdbgen should create new tables. Default is "true".
-
-.^|dropPK
-.^|boolean
-.^|Indicates whether cdbgen should drop Cayenne primary key support objects. Default is "false".
-
-.^|dropTables
-.^|boolean
-.^|Indicates whether cdbgen should drop the tables before attempting to create new ones. Default is "false".
-|===
-
-Example - creating a DB schema on a local HSQLDB database:
-
-[source,xml,subs="verbatim,attributes"]
-----
-<plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>cayenne-maven-plugin</artifactId>
- <version>{version}</version>
- <executions>
- <execution>
- <configuration>
- <map>${project.basedir}/src/main/resources/my.map.xml</map>
- <adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter</adapter>
- <dataSource>
- <url>jdbc:hsqldb:hsql://localhost/testdb</url>
- <driver>org.hsqldb.jdbcDriver</driver>
- <username>sa</username>
- </dataSource>
- </configuration>
- <goals>
- <goal>cdbgen</goal>
- </goals>
- </execution>
- </executions>
-</plugin>
-----
-
-[[mavenCdbimort]]
-===== cdbimport
-
-`cdbimport` is a `cayenne-maven-plugin` goal that generates a DataMap based on an existing database schema. By default, it is bound to the generate-sources phase. This allows you to generate your DataMap prior to building your project, possibly followed by "cgen" execution to generate the classes. CDBImport plugin described in details in chapter <<DB-First Flow>>
-[#cdbimportTable.table.table-bordered]
-.cdbimport parameters
-[cols="2,1,2,5"]
-|===
-|Name |Type |Required |Description
-
-.^|map
-.^|File
-.^|Yes
-.^|DataMap XML file which is the destination of the schema import. Can be an existing file. If this file does not exist, it is created when cdbimport is executed. E.g. `${project.basedir}/src/main/resources/my.map.xml`. If "overwrite" is true (the default), an existing DataMap will be used as a template for the new imported DataMap, i.e. all its entities will be cleared and recreated, but its common settings, such as default Java package, will be preserved (unless changed explicitly in t [...]
-
-.^|cayenneProject
-.^|File
-.^|No
-.^|Project XML file which will be used. Can be an existing file, in this case data map will be added to project if it's not already there. If this file does not exist, it is created when cdbimport is executed. E.g. `${project.basedir}/src/main/resources/cayenne-project.xml`.
-
-.^|adapter
-.^|String
-.^|No
-.^|A Java class name implementing org.apache.cayenne.dba.DbAdapter. This attribute is optional. If not specified, AutoAdapter is used, which will attempt to guess the DB type.
-
-.^|dataSource
-.^|XML
-.^|Yes
-.^|An object that contains Data Source parameters.
-
-.^|dbimport
-.^|XML
-.^|No
-.^|An object that contains detailed reverse engineering rules about what DB objects should be processed. For full information about this parameter see <<DB-First Flow>> chapter.
-|===
-
-[#cdbimportDataSource.table.table-bordered]
-.<dataSource> parameters
-[cols="2,1,2,5"]
-|===
-|Name |Type |Required |Description
-
-.^|driver
-.^|String
-.^|Yes
-.^|A class of JDBC driver to use for the target database.
-
-.^|url
-.^|String
-.^|Yes
-.^|JDBC URL of a target database.
-
-.^|username
-.^|String
-.^|No
-.^|Database user name.
-
-.^|password
-.^|String
-.^|No
-.^|Database user password.
-|===
-
-[#dbimportParameters.table.table-bordered]
-.<dbimport> parameters
-[cols="3,1,4"]
-|===
-|Name |Type|Description
-
-.^|defaultPackage
-.^|String
-.^|A Java package that will be set as the imported DataMap default and a package of all the persistent Java classes. This is a required attribute if the "map" itself does not already contain a default package, as otherwise all the persistent classes will be mapped with no package, and will not compile.
-
-.^|forceDataMapCatalog
-.^|boolean
-.^|Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior) may sometimes be undesirable. If this is the case then setting `forceDataMapCatalog` to `true` will set DbEntity catalog to one in the DataMap. Default value is `false`.
-
-.^|forceDataMapSchema
-.^|boolean
-.^|Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior) may sometimes be undesirable. If this is the case then setting `forceDataMapSchema` to `true` will set DbEntity schema to one in the DataMap. Default value is `false`.
-
-.^|meaningfulPkTables
-.^|String
-.^|A comma-separated list of Perl5 patterns that defines which imported tables should have their primary key columns mapped as ObjAttributes. "*" would indicate all tables.
-
-.^|[[namingStrategy]]namingStrategy
-.^|String
-.^|The naming strategy used for mapping database names to object entity names. Default is `o.a.c.dbsync.naming.DefaultObjectNameGenerator`.
-
-.^|skipPrimaryKeyLoading
-.^|boolean
-.^|Whether to load primary keys. Default "false".
-
-.^|skipRelationshipsLoading
-.^|boolean
-.^|Whether to load relationships. Default "false".
-
-.^|stripFromTableNames
-.^|String
-a|Regex that matches the part of the table name that needs to be stripped off when generating ObjEntity name. Here are some examples:
-[source,XML]
-----
-<!-- Strip prefix -->
-<stripFromTableNames>^myt_</stripFromTableNames>
-
-<!-- Strip suffix -->
-<stripFromTableNames>_s$</stripFromTableNames>
-
-<!-- Strip multiple occurrences in the middle -->
-<stripFromTableNames>_abc</stripFromTableNames>
-----
-
-.^|usePrimitives
-.^|boolean
-.^|Whether numeric and boolean data types should be mapped as Java primitives or Java classes. Default is "true", i.e. primitives will be used.
-
-.^|useJava7Types
-.^|boolean
-.^|Whether _DATE_, _TIME_ and _TIMESTAMP_ data types should be mapped as `java.util.Date` or `java.time.* classes`. Default is "false", i.e. `java.time.*` will be used.
-
-.^|tableTypes
-.^|Collection<String>
-a|Collection of table types to import. By default "TABLE" and "VIEW" types are used.
-Typical types are:
-
-* TABLE
-* VIEW
-* SYSTEM TABLE
-* GLOBAL TEMPORARY
-* LOCAL TEMPORARY
-* ALIAS
-* SYNONYM
-
-.^|filters configuration
-.^|XML
-a|Detailed reverse engineering rules about what DB objects should be processed. For full information about this parameter see <<DB-First Flow>> chapter. Here is some simple example:
-[source,XML]
-----
-<dbimport>
- <catalog name="test_catalog">
- <schema name="test_schema">
- <includeTable>.*</includeTable>
- <excludeTable>test_table</excludeTable>
- </schema>
- </catalog>
-
- <includeProcedure pattern=".*"/>
-</dbimport>
-----
-
-
-|===
-
-Example - loading a DB schema from a local HSQLDB database (essentially a reverse operation compared to the cdbgen example above) :
-
-[source, XML,,subs="verbatim,attributes"]
-----
-<plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>cayenne-maven-plugin</artifactId>
- <version>{version}</version>
-
- <executions>
- <execution>
- <configuration>
- <map>${project.basedir}/src/main/resources/my.map.xml</map>
- <dataSource>
- <url>jdbc:mysql://127.0.0.1/mydb</url>
- <driver>com.mysql.jdbc.Driver</driver>
- <username>sa</username>
- </dataSource>
- <dbimport>
- <defaultPackage>com.example.cayenne</defaultPackage>
- </dbimport>
- </configuration>
- <goals>
- <goal>cdbimport</goal>
- </goals>
- </execution>
- </executions>
-</plugin>
-----
-
==== Gradle Projects
-To include Cayenne into your Gradle project you have two options:
-
-- Simply add Cayenne as a dependency:
+To add Cayenne to your Maven project, include `cayenne-server` module:
[source, Groovy,subs="verbatim,attributes"]
----
compile 'org.apache.cayenne:cayenne-server:{version}'
----
-- Or you can use Cayenne Gradle plugin
-
-===== Gradle Plugin
-
-Cayenne Gradle plugin provides several tasks, such as synching generated Java classes with the mapping or synching mapping with the database. Plugin also provides `cayenne` extension that have some useful utility methods. Here is example of how to include Cayenne plugin into your project:
-
-[source, Groovy, subs="verbatim,attributes"]
-----
-buildscript {
- // add Maven Central repository
- repositories {
- mavenCentral()
- }
- // add Cayenne Gradle Plugin
- dependencies {
- classpath group: 'org.apache.cayenne.plugins', name: 'cayenne-gradle-plugin', version: '{version}'
- }
-}
-
-// apply plugin
-apply plugin: 'org.apache.cayenne'
-
-// set default DataMap
-cayenne.defaultDataMap 'datamap.map.xml'
-
-// add Cayenne dependencies to your project
-dependencies {
- // this is a shortcut for 'org.apache.cayenne:cayenne-server:VERSION_OF_PLUGIN'
- compile cayenne.dependency('server')
-}
-----
-
-====== Warning
-
-Cayenne Gradle plugin is experimental and it's API can change later.
-
-===== cgen
-
-Cgen task generates Java classes based on your DataMap, it has same configuration parameters as in Maven Plugin version, described in xref:tablecgen[Table, “cgen required parameters”.]. If you provided default DataMap via `cayenne.defaultDataMap`, you can skip `cgen` configuration as default settings will suffice in common case.
-
-Here is how you can change settings of the default `cgen` task:
-
-[source, Groovy]
-----
-cgen {
- client = false
- mode = 'all'
- overwrite = true
- createPropertiesNames = true
-}
-----
-
-And here is example of how to define additional cgen task (e.g. for client classes if you are using ROP):
-
-
-[source, Groovy]
-----
-task clientCgen(type: cayenne.cgen) {
- client = true
-}
-----
-
-===== cdbimport
-
-This task is for creating and synchronizing your Cayenne model from database schema. Full list of parameters are same as in Maven Plugin version, described in xref:cdbimportTable[Table, “cdbimport parameters”], with exception that Gradle version will use Groovy instead of XML.
-
-Here is example of configuration for cdbimport task:
-
-[source, Groovy]
-----
-cdbimport {
- // map can be skipped if it is defined in cayenne.defaultDataMap
- map 'datamap.map.xml'
- // optional project file, will be created if missing
- cayenneProject 'cayenne-project.xml'
-
- dataSource {
- driver 'com.mysql.cj.jdbc.Driver'
- url 'jdbc:mysql://127.0.0.1:3306/test?useSSL=false'
- username 'root'
- password ''
- }
-
- dbImport
- // additional settings
- usePrimitives false
- defaultPackage 'org.apache.cayenne.test'
-
- // DB filter configuration
- catalog 'catalog-1'
- schema 'schema-1'
-
- catalog {
- name 'catalog-2'
-
- includeTable 'table0', {
- excludeColumns '_column_'
- }
-
- includeTables 'table1', 'table2', 'table3'
-
- includeTable 'table4', {
- includeColumns 'id', 'type', 'data'
- }
-
- excludeTable '^GENERATED_.*'
- }
-
- catalog {
- name 'catalog-3'
- schema {
- name 'schema-2'
- includeTable 'test_table'
- includeTable 'test_table2', {
- excludeColumn '__excluded'
- }
- }
- }
-
- includeProcedure 'procedure_test_1'
-
- includeColumns 'id', 'version'
-
- tableTypes 'TABLE', 'VIEW'
- }
-}
-----
-
-===== cdbgen
-
-Cdbgen task drops and/or generates tables in a database on Cayenne DataMap. Full list of parameters are same as in Maven Plugin version, described in xref:cdbgenTable[Table , “cdbgen required parameters”]
-
-Here is example of how to configure default `cdbgen` task:
-
-[source, Groovy]
-----
-cdbgen {
-
- adapter 'org.apache.cayenne.dba.derby.DerbyAdapter'
-
- dataSource {
- driver 'org.apache.derby.jdbc.EmbeddedDriver'
- url 'jdbc:derby:build/testdb;create=true'
- username 'sa'
- password ''
- }
-
- dropTables true
- dropPk true
-
- createTables true
- createPk true
- createFk true
-}
-----
-
-===== Link tasks to Gradle build lifecycle
-
-With gradle you can easily connect Cayenne tasks to default build lifecycle. Here is short example of how to connect defaut `cgen` and `cdbimport` tasks with `compileJava` task:
-
-[source, Groovy]
-----
-cgen.dependsOn cdbimport
-compileJava.dependsOn cgen
-----
-
-NOTE: Running `cdbimport` automatically with build not always a good choice, e.g. in case of complex model that you need to alter in the Cayenne Modeler after import.
-
-==== Ant Projects
-
-Ant tasks are the same as Maven plugin goals described above, namely "cgen", "cdbgen", "cdbimport". Configuration parameters are also similar (except Maven can guess many defaults that Ant can't). To include Ant tasks in the project, use the following Antlib:
-
-[source, XML]
-----
-<typedef resource="org/apache/cayenne/tools/antlib.xml">
- <classpath>
- <fileset dir="lib" >
- <include name="cayenne-ant-*.jar" />
- <include name="cayenne-cgen-*.jar" />
- <include name="cayenne-dbsync-*.jar" />
- <include name="cayenne-di-*.jar" />
- <include name="cayenne-project-*.jar" />
- <include name="cayenne-server-*.jar" />
- <include name="commons-collections-*.jar" />
- <include name="commons-lang-*.jar" />
- <include name="slf4j-api-*.jar" />
- <include name="velocity-*.jar" />
- <include name="vpp-2.2.1.jar" />
- </fileset>
- </classpath>
-</typedef>
-----
-
-===== cgen
-
-[source,xml]
-----
-<cgen map="${context.dir}/WEB-INF/my.map.xml"/>
-----
-
-===== cdbgen
-
-===== cdbimport
-
-This is an Ant counterpart of "cdbimport" goal of cayenne-maven-plugin described above. It has exactly the same properties. Here is a usage example:
-
-[source, XML]
-----
- <cdbimport map="${context.dir}/WEB-INF/my.map.xml"
- driver="com.mysql.jdbc.Driver"
- url="jdbc:mysql://127.0.0.1/mydb"
- username="sa"
- defaultPackage="com.example.cayenne"/>
-----
+==== Ant, etc.
+If your environment requires manual dependency management (like Ant), check `lib` and `lib/third-party` folders of
+Cayenne distribution. It contains all Cayenne jars as well as the minimal set of third-party libraries to get you
+started.
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/listOfTables.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part6.adoc
similarity index 50%
rename from docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/listOfTables.adoc
rename to docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part6.adoc
index 001d993..226750e 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/listOfTables.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part6.adoc
@@ -12,19 +12,16 @@
// the specific language governing permissions and limitations under the
// License.
-== List of tables
+[#build_tools]
+== Build Tools
-* xref:versionHistory[Cayenne Version History]
-* xref:pluginParameteres[modeler plugin parameters]
-* xref:tablecgen[cgen required parameters]
-* xref:cgenOptional[cgen optional parameters]
-* xref:cdbgenTable[cdbgen required parameters]
-* xref:dataSourceParameteres[<dataSource> parameters]
-* xref:cdbgenOptionl[cdbgen optional parameters]
-* xref:cdbimportTable[cdbimport parameters]
-* xref:cdbimportDataSource[<dataSource> parameters]
-* xref:dbimportParameters[<dbimport> parameters]
-* xref:persistenceStates[Persistence States]
-* xref:lifecycleEvent[Lifecycle Event Types]
-* xref:configProperties[Configuration Properties Recognized by ServerRuntime and/or ClientRuntime]
-* xref:serviceCollections[Service Collection Keys Present in ServerRuntime and/or ClientRuntime]
\ No newline at end of file
+While we encourage the use of <<cayenne-modeler,CayenneModeler>> for tasks such as DB reverse-engineering and
+code generation, Cayenne also provides an option to execute them from your preferred build tool.
+It may be occasionally useful to keep them as a part of the build. This chapter shows how to use them in
+<<maven_plugin,Maven>>, <<gradle_plugin,Gradle>> or <<ant_tasks,Ant>>.
+
+include::part6/maven-plugin.adoc[]
+
+include::part6/gradle-plugin.adoc[]
+
+include::part6/ant-tasks.adoc[]
\ No newline at end of file
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part6/ant-tasks.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part6/ant-tasks.adoc
new file mode 100644
index 0000000..225f203
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part6/ant-tasks.adoc
@@ -0,0 +1,59 @@
+// 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.
+
+[#ant_tasks]
+=== Ant Tasks
+
+Ant tasks are the same as <<maven_plugin,Maven plugin goals>> described previously, namely "cgen", "cdbgen", "cdbimport".
+Configuration parameters are also similar (except Maven can guess many defaults that Ant can't). To include Ant tasks
+in the project, use the following Antlib:
+
+[source, XML]
+----
+<typedef resource="org/apache/cayenne/tools/antlib.xml">
+ <classpath>
+ <fileset dir="lib" >
+ <include name="cayenne-ant-*.jar" />
+ <include name="cayenne-cgen-*.jar" />
+ <include name="cayenne-dbsync-*.jar" />
+ <include name="cayenne-di-*.jar" />
+ <include name="cayenne-project-*.jar" />
+ <include name="cayenne-server-*.jar" />
+ <include name="commons-collections-*.jar" />
+ <include name="commons-lang-*.jar" />
+ <include name="slf4j-api-*.jar" />
+ <include name="velocity-*.jar" />
+ <include name="vpp-2.2.1.jar" />
+ </fileset>
+ </classpath>
+</typedef>
+----
+
+==== cgen
+
+==== cdbgen
+
+==== cdbimport
+
+This is an Ant counterpart of "cdbimport" goal of cayenne-maven-plugin described above. It has exactly the same
+properties. Here is a usage example:
+
+[source, XML]
+----
+ <cdbimport map="${context.dir}/WEB-INF/my.map.xml"
+ driver="com.mysql.jdbc.Driver"
+ url="jdbc:mysql://127.0.0.1/mydb"
+ username="sa"
+ defaultPackage="com.example.cayenne"/>
+----
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part6/gradle-plugin.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part6/gradle-plugin.adoc
new file mode 100644
index 0000000..e449263
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part6/gradle-plugin.adoc
@@ -0,0 +1,178 @@
+// 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.
+
+[#gradle_plugin]
+=== Gradle Plugin
+
+Cayenne Gradle plugin provides tasks similar to <<maven_plugin,Maven plugin>>. It also provides `cayenne` extension that
+has some useful utility methods. Here is example of how to include Cayenne plugin into your project:
+
+[source, Groovy, subs="verbatim,attributes"]
+----
+buildscript {
+ // add Maven Central repository
+ repositories {
+ mavenCentral()
+ }
+ // add Cayenne Gradle Plugin
+ dependencies {
+ classpath group: 'org.apache.cayenne.plugins', name: 'cayenne-gradle-plugin', version: '{version}'
+ }
+}
+
+// apply plugin
+apply plugin: 'org.apache.cayenne'
+
+// set default DataMap
+cayenne.defaultDataMap 'datamap.map.xml'
+
+// add Cayenne dependencies to your project
+dependencies {
+ // this is a shortcut for 'org.apache.cayenne:cayenne-server:VERSION_OF_PLUGIN'
+ compile cayenne.dependency('server')
+}
+----
+
+NOTE: Cayenne Gradle plugin is experimental and it's API may still change.
+
+==== cgen
+
+Cgen task generates Java classes based on your DataMap, it has same configuration parameters as in Maven Plugin version, described in xref:tablecgen[Table, “cgen required parameters”.]. If you provided default DataMap via `cayenne.defaultDataMap`, you can skip `cgen` configuration as default settings will suffice in common case.
+
+Here is how you can change settings of the default `cgen` task:
+
+[source, Groovy]
+----
+cgen {
+ client = false
+ mode = 'all'
+ overwrite = true
+ createPropertiesNames = true
+}
+----
+
+And here is example of how to define additional cgen task (e.g. for client classes if you are using ROP):
+
+
+[source, Groovy]
+----
+task clientCgen(type: cayenne.cgen) {
+ client = true
+}
+----
+
+==== cdbimport
+
+This task is for creating and synchronizing your Cayenne model from database schema. Full list of parameters are same
+as in <<cdbimportTable,Maven Plugin>>, with the exception that Gradle version will use Groovy instead of XML. Here is
+example of configuration for cdbimport task:
+
+[source, Groovy]
+----
+cdbimport {
+ // map can be skipped if it is defined in cayenne.defaultDataMap
+ map 'datamap.map.xml'
+ // optional project file, will be created if missing
+ cayenneProject 'cayenne-project.xml'
+
+ dataSource {
+ driver 'com.mysql.cj.jdbc.Driver'
+ url 'jdbc:mysql://127.0.0.1:3306/test?useSSL=false'
+ username 'root'
+ password ''
+ }
+
+ dbImport
+ // additional settings
+ usePrimitives false
+ defaultPackage 'org.apache.cayenne.test'
+
+ // DB filter configuration
+ catalog 'catalog-1'
+ schema 'schema-1'
+
+ catalog {
+ name 'catalog-2'
+
+ includeTable 'table0', {
+ excludeColumns '_column_'
+ }
+
+ includeTables 'table1', 'table2', 'table3'
+
+ includeTable 'table4', {
+ includeColumns 'id', 'type', 'data'
+ }
+
+ excludeTable '^GENERATED_.*'
+ }
+
+ catalog {
+ name 'catalog-3'
+ schema {
+ name 'schema-2'
+ includeTable 'test_table'
+ includeTable 'test_table2', {
+ excludeColumn '__excluded'
+ }
+ }
+ }
+
+ includeProcedure 'procedure_test_1'
+
+ includeColumns 'id', 'version'
+
+ tableTypes 'TABLE', 'VIEW'
+ }
+}
+----
+
+==== cdbgen
+
+Cdbgen task drops and/or generates tables in a database on Cayenne DataMap. Full list of parameters is same as in the
+<<cdbgenTable,Maven plugin>>. Here is example of how to configure default `cdbgen` task:
+
+[source, Groovy]
+----
+cdbgen {
+
+ adapter 'org.apache.cayenne.dba.derby.DerbyAdapter'
+
+ dataSource {
+ driver 'org.apache.derby.jdbc.EmbeddedDriver'
+ url 'jdbc:derby:build/testdb;create=true'
+ username 'sa'
+ password ''
+ }
+
+ dropTables true
+ dropPk true
+
+ createTables true
+ createPk true
+ createFk true
+}
+----
+
+==== Link tasks to Gradle build lifecycle
+
+You can connect Cayenne tasks to the default build lifecycle. Here is short example of how to connect
+defaut `cgen` and `cdbimport` tasks with `compileJava` task:
+
+[source, Groovy]
+----
+cgen.dependsOn cdbimport
+compileJava.dependsOn cgen
+----
+
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part6/maven-plugin.adoc
similarity index 61%
copy from docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc
copy to docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part6/maven-plugin.adoc
index b168417..77399e4 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part6/maven-plugin.adoc
@@ -5,55 +5,29 @@
// 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
//
-// https://www.apache.org/licenses/LICENSE-2.0 Unless required by
+// 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.
-include::../var.adoc[]
+[#maven_plugin]
+=== Maven Plugin
-[[including-cayenne-in-project]]
-=== Including Cayenne in a Project
+The full plugin Maven name is `org.apache.cayenne.plugins:cayenne-maven-plugin`. It can be executed as `mvn cayenne:<goal>`.
-==== Jar Files
+[#cgen]
+==== cgen
-This is an overview of Cayenne jars that is agnostic of the build tool used. The following are the important libraries:
+`cgen` is a goal that generates and maintains source (.java) files of persistent objects based
+on a DataMap. By default, it is bound to the generate-sources phase. If "makePairs" is set to "true" (which is the
+recommended default), this task will generate a pair of classes (superclass/subclass) for each ObjEntity in the DataMap.
+Superclasses should not be changed manually, since they are always overwritten. Subclasses are never overwritten and
+may be later customized by the user. If "makePairs" is set to "false", a single class will be generated for each ObjEntity.
-- `cayenne-di-{version}.jar` - Cayenne dependency injection (DI) container library. All applications will require this file.
-
-- `cayenne-server-{version}.jar` - contains main Cayenne runtime (adapters, DB access classes, etc.). Most applications will require this file.
-
-- Other cayenne-* jars - various Cayenne tools extensions.
-
-==== Dependencies
-
-With modern build tools like Maven and Gradle, you should not worry about tracking dependencies. If you have one of those, you can skip this section and go straight to the Maven section below. However if your environment requires manual dependency resolution (like Ant), the distribution provides all of Cayenne jars plus a minimal set of third-party dependencies to get you started in a default configuration. Check lib and `lib/third-party` folders for those.
-
-Dependencies for non-standard configurations will need to be figured out by the users on their own. Check `pom.xml` files of the corresponding Cayenne modules in one of the searchable Maven archives out there to get an idea of those dependencies (e.g. http://search.maven.org).
-
-==== Maven Projects
-
-If you are using Maven, you won't have to deal with figuring out the dependencies. You can simply include cayenne-server artifact in your POM:
-
-[source,xml,subs="verbatim,attributes"]
-----
-<dependency>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-server</artifactId>
- <version>{version}</version>
-</dependency>
-----
-
-Additionally Cayenne provides a Maven plugin with a set of goals to perform various project tasks, such as synching generated Java classes with the mapping, described in the following subsection. The full plugin name is `org.apache.cayenne.plugins:cayenne-maven-plugin`.
-
-[[cgen]]
-===== cgen
-
-`cgen` is a `cayenne-maven-plugin` goal that generates and maintains source (.java) files of persistent objects based on a DataMap. By default, it is bound to the generate-sources phase. If "makePairs" is set to "true" (which is the recommended default), this task will generate a pair of classes (superclass/subclass) for each ObjEntity in the DataMap. Superclasses should not be changed manually, since they are always overwritten. Subclasses are never overwritten and may be later customiz [...]
-
-By creating custom templates, you can use cgen to generate other output (such as web pages, reports, specialized code templates) based on DataMap information.
+By creating custom templates, you can use cgen to generate other output (such as web pages, reports, specialized code
+templates) based on DataMap information.
[#tablecgen.table.table-bordered]
.cgen required parameters
@@ -173,118 +147,8 @@ Example - a typical class generation scenario, where pairs of classes are genera
</plugin>
----
-===== cdbgen
-
-`cdbgen` is a `cayenne-maven-plugin` goal that drops and/or generates tables in a database on Cayenne DataMap. By default, it is bound to the pre-integration-test phase.
-
-[#cdbgenTable.table.table-bordered]
-.cdbgen required parameters
-[cols="1,1,4"]
-|===
-|Name |Type|Description
-
-.^|map
-.^|File
-a|DataMap XML file which serves as a source of metadata for class generation. E.g.
-[source]
-----
-${project.basedir}/src/main/resources/my.map.xml
-----
-
-.^|dataSource
-.^|XML
-.^|An object that contains Data Source parameters
-|===
-
-
-[#dataSourceParameteres.table.table-bordered]
-.<dataSource> parameters
-[cols="2,1,2,5"]
-|===
-|Name |Type |Required |Description
-
-.^|driver
-.^|String
-.^|Yes
-.^|A class of JDBC driver to use for the target database.
-
-.^|url
-.^|String
-.^|Yes
-.^|JDBC URL of a target database.
-
-.^|username
-.^|String
-.^|No
-.^|Database user name.
-
-.^|password
-.^|String
-.^|No
-.^|Database user password.
-|===
-
-[#cdbgenOptionl.table.table-bordered]
-.cdbgen optional parameters
-[cols="1,1,4"]
-|===
-|Name |Type|Description
-
-.^|adapter
-.^|String
-.^|Java class name implementing org.apache.cayenne.dba.DbAdapter. While this attribute is optional (a generic JdbcAdapter is used if not set), it is highly recommended to specify correct target adapter.
-
-
-.^|createFK
-.^|boolean
-.^|Indicates whether cdbgen should create foreign key constraints. Default is "true".
-
-.^|createPK
-.^|boolean
-.^|Indicates whether cdbgen should create Cayenne-specific auto PK objects. Default is "true".
-
-.^|createTables
-.^|boolean
-.^|Indicates whether cdbgen should create new tables. Default is "true".
-
-.^|dropPK
-.^|boolean
-.^|Indicates whether cdbgen should drop Cayenne primary key support objects. Default is "false".
-
-.^|dropTables
-.^|boolean
-.^|Indicates whether cdbgen should drop the tables before attempting to create new ones. Default is "false".
-|===
-
-Example - creating a DB schema on a local HSQLDB database:
-
-[source,xml,subs="verbatim,attributes"]
-----
-<plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>cayenne-maven-plugin</artifactId>
- <version>{version}</version>
- <executions>
- <execution>
- <configuration>
- <map>${project.basedir}/src/main/resources/my.map.xml</map>
- <adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter</adapter>
- <dataSource>
- <url>jdbc:hsqldb:hsql://localhost/testdb</url>
- <driver>org.hsqldb.jdbcDriver</driver>
- <username>sa</username>
- </dataSource>
- </configuration>
- <goals>
- <goal>cdbgen</goal>
- </goals>
- </execution>
- </executions>
-</plugin>
-----
-
-[[mavenCdbimort]]
-===== cdbimport
+[#mavenCdbimort]
+==== cdbimport
`cdbimport` is a `cayenne-maven-plugin` goal that generates a DataMap based on an existing database schema. By default, it is bound to the generate-sources phase. This allows you to generate your DataMap prior to building your project, possibly followed by "cgen" execution to generate the classes. CDBImport plugin described in details in chapter <<DB-First Flow>>
[#cdbimportTable.table.table-bordered]
@@ -466,229 +330,113 @@ Example - loading a DB schema from a local HSQLDB database (essentially a revers
</plugin>
----
-==== Gradle Projects
-
-To include Cayenne into your Gradle project you have two options:
-
-- Simply add Cayenne as a dependency:
-
-[source, Groovy,subs="verbatim,attributes"]
-----
-compile 'org.apache.cayenne:cayenne-server:{version}'
-----
-
-- Or you can use Cayenne Gradle plugin
-
-===== Gradle Plugin
-
-Cayenne Gradle plugin provides several tasks, such as synching generated Java classes with the mapping or synching mapping with the database. Plugin also provides `cayenne` extension that have some useful utility methods. Here is example of how to include Cayenne plugin into your project:
-
-[source, Groovy, subs="verbatim,attributes"]
-----
-buildscript {
- // add Maven Central repository
- repositories {
- mavenCentral()
- }
- // add Cayenne Gradle Plugin
- dependencies {
- classpath group: 'org.apache.cayenne.plugins', name: 'cayenne-gradle-plugin', version: '{version}'
- }
-}
-
-// apply plugin
-apply plugin: 'org.apache.cayenne'
-
-// set default DataMap
-cayenne.defaultDataMap 'datamap.map.xml'
-
-// add Cayenne dependencies to your project
-dependencies {
- // this is a shortcut for 'org.apache.cayenne:cayenne-server:VERSION_OF_PLUGIN'
- compile cayenne.dependency('server')
-}
-----
-
-====== Warning
-
-Cayenne Gradle plugin is experimental and it's API can change later.
-
-===== cgen
-
-Cgen task generates Java classes based on your DataMap, it has same configuration parameters as in Maven Plugin version, described in xref:tablecgen[Table, “cgen required parameters”.]. If you provided default DataMap via `cayenne.defaultDataMap`, you can skip `cgen` configuration as default settings will suffice in common case.
-Here is how you can change settings of the default `cgen` task:
+==== cdbgen
-[source, Groovy]
-----
-cgen {
- client = false
- mode = 'all'
- overwrite = true
- createPropertiesNames = true
-}
-----
-
-And here is example of how to define additional cgen task (e.g. for client classes if you are using ROP):
-
-
-[source, Groovy]
-----
-task clientCgen(type: cayenne.cgen) {
- client = true
-}
-----
-
-===== cdbimport
-
-This task is for creating and synchronizing your Cayenne model from database schema. Full list of parameters are same as in Maven Plugin version, described in xref:cdbimportTable[Table, “cdbimport parameters”], with exception that Gradle version will use Groovy instead of XML.
+`cdbgen` is a `cayenne-maven-plugin` goal that drops and/or generates tables in a database on Cayenne DataMap. By default, it is bound to the pre-integration-test phase.
-Here is example of configuration for cdbimport task:
+[#cdbgenTable.table.table-bordered]
+.cdbgen required parameters
+[cols="1,1,4"]
+|===
+|Name |Type|Description
-[source, Groovy]
-----
-cdbimport {
- // map can be skipped if it is defined in cayenne.defaultDataMap
- map 'datamap.map.xml'
- // optional project file, will be created if missing
- cayenneProject 'cayenne-project.xml'
-
- dataSource {
- driver 'com.mysql.cj.jdbc.Driver'
- url 'jdbc:mysql://127.0.0.1:3306/test?useSSL=false'
- username 'root'
- password ''
- }
-
- dbImport
- // additional settings
- usePrimitives false
- defaultPackage 'org.apache.cayenne.test'
-
- // DB filter configuration
- catalog 'catalog-1'
- schema 'schema-1'
-
- catalog {
- name 'catalog-2'
-
- includeTable 'table0', {
- excludeColumns '_column_'
- }
-
- includeTables 'table1', 'table2', 'table3'
-
- includeTable 'table4', {
- includeColumns 'id', 'type', 'data'
- }
-
- excludeTable '^GENERATED_.*'
- }
-
- catalog {
- name 'catalog-3'
- schema {
- name 'schema-2'
- includeTable 'test_table'
- includeTable 'test_table2', {
- excludeColumn '__excluded'
- }
- }
- }
-
- includeProcedure 'procedure_test_1'
-
- includeColumns 'id', 'version'
-
- tableTypes 'TABLE', 'VIEW'
- }
-}
+.^|map
+.^|File
+a|DataMap XML file which serves as a source of metadata for class generation. E.g.
+[source]
----
-
-===== cdbgen
-
-Cdbgen task drops and/or generates tables in a database on Cayenne DataMap. Full list of parameters are same as in Maven Plugin version, described in xref:cdbgenTable[Table , “cdbgen required parameters”]
-
-Here is example of how to configure default `cdbgen` task:
-
-[source, Groovy]
+${project.basedir}/src/main/resources/my.map.xml
----
-cdbgen {
- adapter 'org.apache.cayenne.dba.derby.DerbyAdapter'
+.^|dataSource
+.^|XML
+.^|An object that contains Data Source parameters
+|===
- dataSource {
- driver 'org.apache.derby.jdbc.EmbeddedDriver'
- url 'jdbc:derby:build/testdb;create=true'
- username 'sa'
- password ''
- }
- dropTables true
- dropPk true
+[#dataSourceParameteres.table.table-bordered]
+.<dataSource> parameters
+[cols="2,1,2,5"]
+|===
+|Name |Type |Required |Description
- createTables true
- createPk true
- createFk true
-}
-----
+.^|driver
+.^|String
+.^|Yes
+.^|A class of JDBC driver to use for the target database.
-===== Link tasks to Gradle build lifecycle
+.^|url
+.^|String
+.^|Yes
+.^|JDBC URL of a target database.
-With gradle you can easily connect Cayenne tasks to default build lifecycle. Here is short example of how to connect defaut `cgen` and `cdbimport` tasks with `compileJava` task:
+.^|username
+.^|String
+.^|No
+.^|Database user name.
-[source, Groovy]
-----
-cgen.dependsOn cdbimport
-compileJava.dependsOn cgen
-----
+.^|password
+.^|String
+.^|No
+.^|Database user password.
+|===
-NOTE: Running `cdbimport` automatically with build not always a good choice, e.g. in case of complex model that you need to alter in the Cayenne Modeler after import.
+[#cdbgenOptionl.table.table-bordered]
+.cdbgen optional parameters
+[cols="1,1,4"]
+|===
+|Name |Type|Description
-==== Ant Projects
+.^|adapter
+.^|String
+.^|Java class name implementing org.apache.cayenne.dba.DbAdapter. While this attribute is optional (a generic JdbcAdapter is used if not set), it is highly recommended to specify correct target adapter.
-Ant tasks are the same as Maven plugin goals described above, namely "cgen", "cdbgen", "cdbimport". Configuration parameters are also similar (except Maven can guess many defaults that Ant can't). To include Ant tasks in the project, use the following Antlib:
-[source, XML]
-----
-<typedef resource="org/apache/cayenne/tools/antlib.xml">
- <classpath>
- <fileset dir="lib" >
- <include name="cayenne-ant-*.jar" />
- <include name="cayenne-cgen-*.jar" />
- <include name="cayenne-dbsync-*.jar" />
- <include name="cayenne-di-*.jar" />
- <include name="cayenne-project-*.jar" />
- <include name="cayenne-server-*.jar" />
- <include name="commons-collections-*.jar" />
- <include name="commons-lang-*.jar" />
- <include name="slf4j-api-*.jar" />
- <include name="velocity-*.jar" />
- <include name="vpp-2.2.1.jar" />
- </fileset>
- </classpath>
-</typedef>
-----
+.^|createFK
+.^|boolean
+.^|Indicates whether cdbgen should create foreign key constraints. Default is "true".
-===== cgen
+.^|createPK
+.^|boolean
+.^|Indicates whether cdbgen should create Cayenne-specific auto PK objects. Default is "true".
-[source,xml]
-----
-<cgen map="${context.dir}/WEB-INF/my.map.xml"/>
-----
+.^|createTables
+.^|boolean
+.^|Indicates whether cdbgen should create new tables. Default is "true".
-===== cdbgen
+.^|dropPK
+.^|boolean
+.^|Indicates whether cdbgen should drop Cayenne primary key support objects. Default is "false".
-===== cdbimport
+.^|dropTables
+.^|boolean
+.^|Indicates whether cdbgen should drop the tables before attempting to create new ones. Default is "false".
+|===
-This is an Ant counterpart of "cdbimport" goal of cayenne-maven-plugin described above. It has exactly the same properties. Here is a usage example:
+Example - creating a DB schema on a local HSQLDB database:
-[source, XML]
+[source,xml,subs="verbatim,attributes"]
----
- <cdbimport map="${context.dir}/WEB-INF/my.map.xml"
- driver="com.mysql.jdbc.Driver"
- url="jdbc:mysql://127.0.0.1/mydb"
- username="sa"
- defaultPackage="com.example.cayenne"/>
+<plugin>
+ <groupId>org.apache.cayenne.plugins</groupId>
+ <artifactId>cayenne-maven-plugin</artifactId>
+ <version>{version}</version>
+ <executions>
+ <execution>
+ <configuration>
+ <map>${project.basedir}/src/main/resources/my.map.xml</map>
+ <adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter</adapter>
+ <dataSource>
+ <url>jdbc:hsqldb:hsql://localhost/testdb</url>
+ <driver>org.hsqldb.jdbcDriver</driver>
+ <username>sa</username>
+ </dataSource>
+ </configuration>
+ <goals>
+ <goal>cdbgen</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
----
-
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/cayenne-guide.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/cayenne-guide.adoc
index a712e1f..ef689ee 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/cayenne-guide.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/cayenne-guide.adoc
@@ -45,6 +45,8 @@ include::_cayenne-guide/part4.adoc[]
include::_cayenne-guide/part5.adoc[]
+include::_cayenne-guide/part6.adoc[]
+
// move ROP docs down
include::_cayenne-guide/part3.adoc[]
@@ -54,5 +56,3 @@ include::_cayenne-guide/serviceCollections.adoc[]
//include::_cayenne-guide/expressionsBNF.adoc[]
-include::_cayenne-guide/listOfTables.adoc[]
-