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 <and...@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[]
-
