You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by nt...@apache.org on 2018/01/05 13:10:35 UTC
[08/13] cayenne git commit: CAY-2371 Switch documentation from
Docbook to Asciidoctor format
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/starting.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/starting.adoc b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/starting.adoc
new file mode 100644
index 0000000..60a3f17
--- /dev/null
+++ b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/starting.adoc
@@ -0,0 +1,93 @@
+// 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.
+
+include::../var.adoc[]
+
+=== Starting Client Project
+
+==== Create an ROP Client Project in Eclipse
+
+Creation of a new Eclipse project has been discussed in some details in "Getting Started with Cayenne" guide, so we will omit the screenshots for the common parts.
+
+In Eclipse select "File > New > Other..." and then "Maven > Maven Project". Click "Next". On the following screen check "Create a simple project" checkbox and click "Next" again. In the dialog shown on the screenshot below, enter "org.example.cayenne" for the "Group Id" and "tutorial-rop-client" for the "Artifact Id" (both without the quotes) and click "Finish".
+
+Now you should have a new empty project in the Eclipse workspace. Check that the project Java compiler settings are correct. Rightclick on the "tutorial-rop-client" project, select "Properties > Java Compiler" and ensure that "Compiler compliance level" is at least 1.5 (some versions of Maven plugin seem to be setting it to 1.4 by default).
+
+==== Create Client Java Classes
+
+The client doesn't need the XML ORM mapping, as it is loaded from the server. However it needs the client-side Java classes. Let's generate them from the existing mapping:
+
+* Start CayenneModeler and open cayenne.xml from the "tutorial" project (located under "tutorial/src/main/resources", unless it is already open.
+
+* Select the "datamap" DataMap and check "Allow Client Entities" checkbox.
+
+* Enter "org.example.cayenne.persistent.client" for the "Client Java Package" and click "Update.." button next to the field to refresh the client package of all entities.
+
+image::../images/datamap-enableclient.png[align="center"]
+
+* Select "Tools > Generate Classes" menu.
+
+* For "Type" select "Client Persistent Objects".
+
+* For the "Output Directory" select "tutorial-rop-client/src/main/java" folder (as client classes should go in the client project).
+
+* Click on "Classes" tab and check the "Check All Classes" checkbox (unless it is already checked and reads "Uncheck all Classes").
+
+* Click "Generate".
+
+Now go back to Eclipse, right click on "tutorial-rop-client" project and select "Refresh" - you should see pairs of classes generated for each mapped entity, same as on the server. And again, we see a bunch of errors in those classes. Let's fix it now by adding two dependencies, "cayenne-client" and "resin-hessian", in the bottom of the pom.xml file. We also need to add Caucho M2 repository to pull Hessian jar files. The resulting POM should look like this:
+
+[source, XML,subs="verbatim,attributes"]
+----
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.example.cayenne</groupId>
+ <artifactId>tutorial-rop-client</artifactId>
+ <version>0.0.1-SNAPSHOT</version>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.cayenne</groupId>
+ <artifactId>cayenne-client</artifactId>
+ <!-- Here specify the version of Cayenne you are actually using -->
+ <version>{version}</version>
+ </dependency>
+ <dependency>
+ <groupId>com.caucho</groupId>
+ <artifactId>hessian</artifactId>
+ <version>4.0.38</version>
+ </dependency>
+ </dependencies>
+
+ <repositories>
+ <repository>
+ <id>caucho</id>
+ <name>Caucho Repository</name>
+ <url>http://caucho.com/m2</url>
+ <layout>default</layout>
+ <snapshots>
+ <enabled>false</enabled>
+ </snapshots>
+ <releases>
+ <enabled>true</enabled>
+ </releases>
+ </repository>
+ </repositories>
+</project>
+----
+
+Your computer must be connected to the internet. Once you save the pom.xml, Eclipse will download the needed jar files and add them to the project build path. After that all the errors should disappear.
+
+Now let's check the entity class pairs. They look almost identical to their server counterparts, although the superclass and the property access code are different. At this point these differences are somewhat academic, so let's go on with the tutorial.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/var.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/var.adoc b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/var.adoc
new file mode 100644
index 0000000..e575eda
--- /dev/null
+++ b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/var.adoc
@@ -0,0 +1 @@
+:version: {project-version}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/getting-started-rop.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-rop/src/docs/asciidoc/getting-started-rop.adoc b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/getting-started-rop.adoc
new file mode 100644
index 0000000..a58024b
--- /dev/null
+++ b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/getting-started-rop.adoc
@@ -0,0 +1,45 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to you under the Apache License, Version
+// 2.0 (the "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0 Unless required by
+// applicable law or agreed to in writing, software distributed under the
+// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+// CONDITIONS OF ANY KIND, either express or implied. See the License for
+// the specific language governing permissions and limitations under the
+// License.
+= Getting Started with Cayenne ROP (Remote Object Persistence)
+:revnumber: {project-major-version} ({project-version})
+// enable section numbering, limiting depth to 2
+:sectnums:
+:sectnumlevels: 2
+// use custom header
+:cayenne-header: _getting-started-rop/header.html
+:cayenne-header-position: body
+// customize final layout
+//:linkcss:
+// base path to java code include
+:cayenne-root: {basedir}/../../..
+
+[small]#Copyright © 2011-2017 Apache Software Foundation and individual authors#
+
+.License
+[small]#_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_#
+
+[small]#_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::_getting-started-rop/part1.adoc[]
+
+include::_getting-started-rop/part2.adoc[]
+
+
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/images/datamap-enableclient.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-rop/src/docs/asciidoc/images/datamap-enableclient.png b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/images/datamap-enableclient.png
new file mode 100644
index 0000000..62a2af2
Binary files /dev/null and b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/images/datamap-enableclient.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/pom.xml
----------------------------------------------------------------------
diff --git a/docs/asciidoc/pom.xml b/docs/asciidoc/pom.xml
new file mode 100644
index 0000000..2cf01b5
--- /dev/null
+++ b/docs/asciidoc/pom.xml
@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ ~ 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.
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+ <parent>
+ <artifactId>cayenne-docs-parent</artifactId>
+ <groupId>org.apache.cayenne.docs</groupId>
+ <version>4.0.B3-SNAPSHOT</version>
+ </parent>
+
+ <artifactId>cayenne-asciidoc-parent</artifactId>
+ <name>cayenne-asciidoc: Cayenne AsciiDoc Documentation parent</name>
+ <modelVersion>4.0.0</modelVersion>
+ <packaging>pom</packaging>
+
+ <modules>
+ <module>cayenne-asciidoc-extension</module>
+ <module>cayenne-guide</module>
+ <module>getting-started-guide</module>
+ <module>getting-started-rop</module>
+ <module>upgrade-guide</module>
+ </modules>
+
+ <properties>
+ <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+ <asciidoctorj.version>1.5.6</asciidoctorj.version>
+ <asciidoctor.maven.plugin.version>1.5.6</asciidoctor.maven.plugin.version>
+ <asciidoctorj.pdf.version>1.5.0-alpha.16</asciidoctorj.pdf.version>
+ <jruby.version>9.1.14.0</jruby.version>
+ <cayenne.major.version>4.0</cayenne.major.version>
+ </properties>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.cayenne</groupId>
+ <artifactId>cayenne-server</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctorj</artifactId>
+ <version>${asciidoctorj.version}</version>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <pluginManagement>
+ <plugins>
+ <plugin>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctor-maven-plugin</artifactId>
+ <version>${asciidoctor.maven.plugin.version}</version>
+ <dependencies>
+ <dependency>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctorj-pdf</artifactId>
+ <version>${asciidoctorj.pdf.version}</version>
+ </dependency>
+ </dependencies>
+ </plugin>
+ </plugins>
+ </pluginManagement>
+
+ <plugins>
+ <plugin>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctor-maven-plugin</artifactId>
+ <configuration>
+ <sourceDirectory>src/docs/asciidoc</sourceDirectory>
+ <doctype>book</doctype>
+ <!-- Attributes common to all output formats -->
+ <attributes>
+ <endpoint-url>http://cayenne.apache.org</endpoint-url>
+
+ <basedir>${project.basedir}</basedir>
+ <sourcedir>${project.build.sourceDirectory}</sourcedir>
+ <project-version>${project.version}</project-version>
+ <project-major-version>${cayenne.major.version}</project-major-version>
+
+ <imagesdir>images</imagesdir>
+ <icons>font</icons>
+
+ <sectanchors>true</sectanchors>
+ <idprefix/> <!-- set the idprefix to blank -->
+ <idseparator>-</idseparator>
+ <!--
+ currently it is not possible to specify header location inside final document, so can't use
+ asciidoc's *-docinfo.html as header, instead we use extension that deal with our header
+ -->
+ <!--<docinfo>private</docinfo1>-->
+ </attributes>
+ </configuration>
+ <dependencies>
+ <dependency>
+ <groupId>org.jruby</groupId>
+ <artifactId>jruby-complete</artifactId>
+ <version>${jruby.version}</version>
+ </dependency>
+ </dependencies>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <source>1.8</source>
+ <target>1.8</target>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+</project>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/upgrade-guide/pom.xml
----------------------------------------------------------------------
diff --git a/docs/asciidoc/upgrade-guide/pom.xml b/docs/asciidoc/upgrade-guide/pom.xml
new file mode 100644
index 0000000..94818a0
--- /dev/null
+++ b/docs/asciidoc/upgrade-guide/pom.xml
@@ -0,0 +1,151 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <parent>
+ <artifactId>cayenne-asciidoc-parent</artifactId>
+ <groupId>org.apache.cayenne.docs</groupId>
+ <version>4.0.B3-SNAPSHOT</version>
+ </parent>
+ <modelVersion>4.0.0</modelVersion>
+
+ <artifactId>upgrade-guide</artifactId>
+
+ <packaging>jar</packaging>
+ <name>upgrade-guide: AsciiDoc - 4.0 Features Guide</name>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctor-maven-plugin</artifactId>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.cayenne.docs</groupId>
+ <artifactId>cayenne-asciidoc-extension</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ </dependencies>
+
+ <executions>
+ <!-- generate "embeddable" html content with front matter and without header/footer/styles -->
+ <execution>
+ <id>asciidoctor-html-web</id>
+ <phase>generate-resources</phase>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <configuration>
+ <backend>html5</backend>
+ <headerFooter>false</headerFooter> <!-- do not generate header and footer -->
+ <outputDirectory>${project.build.directory}/tmp/</outputDirectory>
+ <extensions>
+ <extension>
+ <className>org.apache.cayenne.asciidoc.CayennePostProcessor</className>
+ </extension>
+ </extensions>
+ <attributes>
+ <toc>auto</toc>
+ </attributes>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+
+ <!-- Move images to proper path for site -->
+ <plugin>
+ <artifactId>maven-resources-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>copy docs for site</id>
+ <phase>install</phase>
+ <goals>
+ <goal>copy-resources</goal>
+ </goals>
+
+ <configuration>
+ <outputDirectory>${project.build.directory}/site/</outputDirectory>
+ <resources>
+ <resource>
+ <directory>${project.build.directory}/tmp/</directory>
+ <includes>
+ <include>${project.artifactId}.html</include>
+ <include>${project.artifactId}.toc.html</include>
+ </includes>
+ </resource>
+ </resources>
+ </configuration>
+ </execution>
+
+ <execution>
+ <id>copy images for site</id>
+ <phase>install</phase>
+ <goals>
+ <goal>copy-resources</goal>
+ </goals>
+
+ <configuration>
+ <outputDirectory>${project.build.directory}/site/${project.artifactId}/images/</outputDirectory>
+ <resources>
+ <resource>
+ <directory>${project.build.directory}/tmp/images/</directory>
+ <filtering>true</filtering>
+ </resource>
+ </resources>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+
+ <profiles>
+ <profile>
+ <id>assembly</id>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctor-maven-plugin</artifactId>
+ <executions>
+ <!-- generate standalone html help -->
+ <execution>
+ <id>asciidoctor-html-standalone</id>
+ <phase>generate-resources</phase>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <configuration>
+ <backend>html5</backend>
+ <sourceHighlighter>coderay</sourceHighlighter>
+ <embedAssets>true</embedAssets>
+ <attributes>
+ <toc>left</toc>
+ </attributes>
+ </configuration>
+ </execution>
+
+ <!-- generate PDF -->
+ <execution>
+ <id>generate-pdf-doc</id>
+ <phase>generate-resources</phase>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <configuration>
+ <backend>pdf</backend>
+ <sourceHighlighter>coderay</sourceHighlighter>
+ <attributes>
+ <pagenums/>
+ <toc/>
+ </attributes>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ </profile>
+ </profiles>
+
+</project>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade_guide/features.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade_guide/features.adoc b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade_guide/features.adoc
new file mode 100644
index 0000000..38f6478
--- /dev/null
+++ b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade_guide/features.adoc
@@ -0,0 +1,245 @@
+// 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.
+
+== Guide to 4.0 Features
+
+This guide highlights the new features and changes introduced in Apache Cayenne 4.0. For a full list of changes consult RELEASE-NOTES.txt included in Cayenne download. For release-specific upgrade instructions check UPGRADE.txt.
+
+=== Java Version
+
+Minimum required JDK version is 1.7 or newer. Cayenne 4.0 is fully tested with Java 1.7, 1.8.
+
+The examples below often use Java 8 syntax. But those same examples should work without lambdas just as well.
+
+=== Cayenne Configuration
+
+==== ServerRuntimeBuilder
+
+Cayenne 3.1 introduced dependency injection and ServerRuntime. 4.0 provides a very convenient utility to create a custom runtime with various extensions. This reduces the code needed to integrate Cayenne in your environment to just a few lines and no boilerplate. E.g.:
+
+[source, java]
+----
+ServerRuntime runtime = ServerRuntime.builder("myproject")
+ .addConfigs("cayenne-project1.xml", "cayenne-project2.xml")
+ .addModule(binder -> binder.bind(JdbcEventLogger.class).toInstance(myLogger))
+ .dataSource(myDataSource)
+ .build();
+----
+
+==== Mapping-free ServerRuntime
+
+ServerRuntime can now be started without any ORM mapping at all. This is useful in situations when Cayenne is used as a stack to execute raw SQL, in unit tests, etc.
+
+==== DI Container Decorators
+
+In addition to overriding services in DI container, Cayenne now allows to supply decorators. True to the "smallest-footprint" DI philosophy, decorator approach is very simple and does not require proxies or class enhancement. Just implement the decorated interface and provide a constructor that takes a delegate instance being decorated:
+
+[source, java]
+----
+public class MyInterfaceDecorator implements MyInterface {
+
+ private MyInterface delegate;
+
+ public MockInterface1_Decorator3(@Inject MyInterface delegate) {
+ this.delegate = delegate;
+ }
+
+ @Override
+ public String getName() {
+ return "<" + delegate.getName() + ">";
+ }
+}
+
+Module module = binder ->
+ binder.decorate(MyInterface.class).before(MyInterfaceDecorator.class);
+----
+
+=== Framework API
+
+==== Fluent Query API
+
+Fluent Query API is one of the most exciting new features in Cayenne 4.0. This syntax is "chainable" so you can write query assembly and execution code on one line. The most useful fluent queries are ObjectSelect, SQLSelect and SelectById:
+
+===== ObjectSelect
+
+A "chainable" analog of SelectQuery.
+
+[source, java]
+----
+Artist a = ObjectSelect
+ .query(Artist.class)
+ .where(Artist.ARTIST_NAME.eq("Picasso"))
+ .selectOne(context);
+----
+
+===== ColumnSelect
+
+This query allows you directly access individual properties of Objects and use functions (including aggregate) via type-safe API.
+
+[source, java]
+----
+List<String> names = ObjectSelect
+ .columnQuery(Artist.class, Artist.ARTIST_NAME)
+ .where(Artist.ARTIST_NAME.length().gt(6))
+ .select(context);
+----
+
+===== SQLSelect
+
+A "chainable" analog of SQLTemplate used specifically to run selecting raw SQL:
+
+[source, java]
+----
+List<Long> ids = SQLSelect
+ .scalarQuery(Long.class, "SELECT ARTIST_ID FROM ARTIST ORDER BY ARTIST_ID")
+ .select(context);
+----
+
+===== SelectById
+
+There's really no good analog of SelectById in Cayenne prior to 4.0. Previously available ObjectIdQuery didn't support half of the features of SelectById (e.g. caching consistent with other queries, prefetches, etc.) :
+
+[source, java]
+----
+Artist a = SelectById
+ .query(Artist.class, 3)
+ .useLocalCache("g1")
+ .selectOne(context)
+----
+
+==== ObjectContext
+
+===== Callback-based Object Iterator
+
+ObjectContext now features a simpler way to iterate over large result sets, based on callback interface that can be implemented with a lambda:
+
+[source, java]
+----
+SelectQuery<Artist> q = new SelectQuery<Artist>(Artist.class);
+
+context.iterate(q, (Artist a) -> {
+ // do something with the object...
+ ...
+});
+----
+
+==== Generics in Expressions and Queries
+
+We finished the work of "genericizing" Cayenne APIs started in 3.1. Now all APIs dealing with persistent objects (Expressions, Queries, ObjectContext, etc.) support generics of Persistent object type or attribute property type.
+
+==== Property API
+
+Persistent superclasses (_MyEntity) now contain a set of static Property<T> variables generated from the model. These metadata objects make possible to create type-safe Expressions and other query parts.
+
+==== Positional Parameter Bindings
+
+Expressions and SQLTemplate traditionally supported binding of parameters by name as a map. Cayenne 4.0 introduces a very easy form of positional bindings. It works with the same named template format, only parameters are bound by position, left-to-right. Here we showing a more complex example with the same parameter name being used more than once in the query:
+
+[source, java]
+----
+// two distinct names, 3 positional parameters.
+// "price" is set to 23, "maxPrice" - to 50
+Expression e = ExpressionFactory.exp(
+ "price = $price or averagePrice = $price and maxPrice = $maxPrice", 23, 50);
+----
+
+This API is supported in Expressions, SQLTemplate as well as new SQLSelect and can be used interchnageably with named parameters with a single template flavor.
+
+==== Improved Transaction API
+
+Transaction factory is now setup via DI (instead of being configured in the Modeler). There's a utility method on ServerRuntime to perform multiple operations as one transaction:
+
+[source, java]
+----
+runtime.performInTransaction(() -> {
+ // ... do some changes
+ context.commitChanges();
+
+ // ... do more changes
+ context.commitChanges();
+
+ return true;
+});
+----
+
+==== Transparent Database Cryptography with "cayenne-crypto" Module
+
+Cayenne includes a new module called "cayenne-crypto" that enables transparent cryptography for designated data columns. This is a pretty cool feature that allows to enable encryption/decryption of your sensitive data pretty much declaratively using your regular DB storage. Encrypted values can be stored in (VAR)BINARY and (VAR)CHAR columns. Currently "cayenne-crypto" supports AES/CBC/PKCS5Padding encryption (though other cyphers can be added). It also supports encrypted data compression. Here is an example of building a crypto DI module that can be added to ServerRuntime:
+
+[source, java]
+----
+Module cryptoExtensions = CryptoModule.extend()
+ .keyStore("file:///mykeystore", "keystorepassword".toCharArray(), "keyalias")
+ .compress()
+ .module();
+----
+
+=== CayenneModeler
+
+==== Improved UI
+
+CayenneModeler features a number of UI improvements. Attributes and relationships are now edited in the same view (no need to switch between the tabs). Project tree allows to easily filter elements by type and quickly collapse the tree.
+
+==== Dropped Support for Mapping Listeners
+
+Managing listeners in the DataMap XML model is counterproductive and confusing, so support for listeners was removed from both the XML and the Modeler. If you previously had listeners mapped in the model, annotate their callback methods, and perform listener registration in the code:
+
+[source, java]
+----
+runtime.getDataDomain().addListener(myListener);
+----
+
+or via DI:
+
+[source, java]
+----
+Module module = binder -> ServerModule.contributeDomainListeners(myListener);
+----
+
+Entity callbacks on the other hand are managed in the Modeler as before.
+
+=== Build Tools
+
+==== cdbimport
+
+"cdbimport" has evolved from an experiment to a full-featured production tool that significantly reduces (and sometimes eliminates) the need for manual maintenance of the DataMaps in CayenneModeler. Two improvements made this possible. First, smart merge algorithm will ensure that custom changes to the model are not overridden on subsequent runs of "cdbimport". Second, the mechanism for specifing DB reverse-engineering parameters, such as name filtering, is made much more powerful with many new options. E.g. we started supporting filters by catalogs and schemas, table name filters can be added per catalog/schema or at the top level, etc.
+
+==== cgen
+
+As was mentioned above, cgen now includes Property<T> static variables for expression building. It is also made smarter about its defaults for "destDir" and "superPkg".
+
+==== Gradle Plugin
+
+Cayenne now provides it's own Gradle Plugin that allows you easily integrate cdbimport and cgen tools into your build process. Here is example of it's usage:
+
+[source, Groovy]
+----
+buildscript {
+ repositories {
+ mavenCentral()
+ }
+ dependencies {
+ classpath group: 'org.apache.cayenne.plugins', name: 'cayenne-gradle-plugin', version: '4.0.B2'
+ }
+}
+
+apply plugin: 'org.apache.cayenne'
+
+cayenne.defaultDataMap 'datamap.map.xml'
+
+dependencies {
+ compile cayenne.dependency('server')
+ compile cayenne.dependency('java8')
+}
+----
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade_guide/header.html
----------------------------------------------------------------------
diff --git a/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade_guide/header.html b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade_guide/header.html
new file mode 100644
index 0000000..be3bea3
--- /dev/null
+++ b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade_guide/header.html
@@ -0,0 +1,24 @@
+---
+# 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.
+
+title: "Guide to 4.0 Features"
+description: "This guide highlights the new features and changes introduced in Apache Cayenne 4.0"
+cayenneVersion: "4.0"
+docsMenuTitle: "Upgrade Guide"
+weight: 50
+---
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/upgrade-guide.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/upgrade-guide/src/docs/asciidoc/upgrade-guide.adoc b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/upgrade-guide.adoc
new file mode 100644
index 0000000..e511cb3
--- /dev/null
+++ b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/upgrade-guide.adoc
@@ -0,0 +1,44 @@
+// 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.
+= Cayenne 4.0 New Features and Upgrade Guide
+:revnumber: {project-major-version} ({project-version})
+// enable section numbering, limiting depth to 2
+:sectnums:
+:sectnumlevels: 2
+// use custom header
+:cayenne-header: _upgrade_guide/header.html
+:cayenne-header-position: body
+// customize final layout
+//:linkcss:
+// base path to java code include
+:cayenne-root: {basedir}/../../..
+
+[small]#Copyright © 2011-2017 Apache Software Foundation and individual authors#
+
+.License
+[small]#_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_#
+
+[small]#_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::_upgrade_guide/features.adoc[]
+
+
+
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/pom.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/pom.xml b/docs/docbook/cayenne-guide/pom.xml
deleted file mode 100644
index 1327a67..0000000
--- a/docs/docbook/cayenne-guide/pom.xml
+++ /dev/null
@@ -1,31 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- 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.
--->
-
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
- <parent>
- <groupId>org.apache.cayenne.docs</groupId>
- <artifactId>cayenne-docbook</artifactId>
- <version>4.0.B3-SNAPSHOT</version>
- </parent>
-
- <modelVersion>4.0.0</modelVersion>
- <artifactId>cayenne-guide</artifactId>
- <name>cayenne-guide: Docbook - Cayenne Guide</name>
-</project>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/appendix-a.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/appendix-a.xml b/docs/docbook/cayenne-guide/src/docbkx/appendix-a.xml
deleted file mode 100644
index f75ba15..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/appendix-a.xml
+++ /dev/null
@@ -1,190 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- 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.
--->
-<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="configuration-properties">
- <title>Configuration Properties</title>
- <para>Note that the property names below are defined as constants in
- <code>org.apache.cayenne.configuration.Constants</code> interface. </para>
- <para>
- <table frame="void">
- <caption>Configuration Properties Recognized by ServerRuntime and/or ClientRuntime</caption>
- <col width="67%"/>
- <col width="15%"/>
- <col width="18%"/>
- <thead>
- <tr>
- <th>Property</th>
- <th>Possible Values</th>
- <th>Default Value</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>cayenne.jdbc.driver[.domain_name.node_name]</code> - defines a JDBC driver class to
- use when creating a DataSource. If domain name and optionally - node name
- are specified, the setting overrides DataSource info just for this
- domain/node. Otherwise the override is applied to all domains/nodes in the
- system.</td>
- <td/>
- <td>none, project DataNode configuration is used</td>
- </tr>
- <tr>
- <td><code>cayenne.jdbc.url[.domain_name.node_name] </code>- defines a DB URL to use when
- creating a DataSource. If domain name and optionally - node name are
- specified, the setting overrides DataSource info just for this domain/node.
- Otherwise the override is applied to all domains/nodes in the system.</td>
- <td/>
- <td>none, project DataNode configuration is used</td>
- </tr>
- <tr>
- <td><code>cayenne.jdbc.username[.domain_name.node_name] </code>- defines a DB user name to use
- when creating a DataSource. If domain name and optionally - node name are
- specified, the setting overrides DataSource info just for this domain/node.
- Otherwise the override is applied to all domains/nodes in the system.</td>
- <td/>
- <td>none, project DataNode configuration is used</td>
- </tr>
- <tr>
- <td><code>cayenne.jdbc.password[.domain_name.node_name]</code> - defines a DB password to use
- when creating a DataSource. If domain name and optionally - node name are
- specified, the setting overrides DataSource info just for this domain/node.
- Otherwise the override is applied to all domains/nodes in the system</td>
- <td/>
- <td>none, project DataNode configuration is used</td>
- </tr>
- <tr>
- <td><code>cayenne.jdbc.min_connections[.domain_name.node_name]</code> - defines the DB
- connection pool minimal size. If domain name and optionally - node name are
- specified, the setting overrides DataSource info just for this domain/node.
- Otherwise the override is applied to all domains/nodes in the system</td>
- <td/>
- <td>none, project DataNode configuration is used</td>
- </tr>
- <tr>
- <td><code>cayenne.jdbc.max_connections[.domain_name.node_name]</code> - defines the DB
- connection pool maximum size. If domain name and optionally - node name are
- specified, the setting overrides DataSource info just for this domain/node.
- Otherwise the override is applied to all domains/nodes in the system</td>
- <td/>
- <td>none, project DataNode configuration is used</td>
- </tr>
- <tr>
- <td><code>cayenne.querycache.size</code> - An integer defining the maximum number of entries in
- the query cache. Note that not all QueryCache providers may respect this
- property. MapQueryCache uses it, but the rest would use alternative
- configuration methods.</td>
- <td>any positive int value</td>
- <td>2000</td>
- </tr>
- <tr>
- <td><code>cayenne.server.contexts_sync_strategy</code> - defines whether peer ObjectContexts
- should receive snapshot events after commits from other contexts. If true
- (default), the contexts would automatically synchronize their state with
- peers.</td>
- <td>true, false</td>
- <td>true</td>
- </tr>
- <tr>
- <td><code>cayenne.server.object_retain_strategy</code> - defines fetched objects retain
- strategy for ObjectContexts. When weak or soft strategy is used, objects
- retained by ObjectContext that have no local changes can potetially get
- garbage collected when JVM feels like doing it.</td>
- <td>weak, soft, hard</td>
- <td>weak</td>
- </tr>
- <tr>
- <td><code>cayenne.server.max_id_qualifier_size</code> - defines a maximum number of ID
- qualifiers in the WHERE clause of queries that are generated for paginated
- queries and for DISJOINT_BY_ID prefetch processing. This is needed to avoid
- hitting WHERE clause size limitations and memory usage efficiency.</td>
- <td>any positive int</td>
- <td>10000</td>
- </tr>
- <tr>
- <td><code>cayenne.server.external_tx</code> - defines whether runtime should use
- external transactions.</td>
- <td>true, false</td>
- <td>false</td>
- </tr>
- <tr>
- <td><code>cayenne.rop.service_url</code> - defines the URL of the ROP server</td>
- <td/>
- <td/>
- </tr>
- <tr>
- <td><code>cayenne.rop.service_username</code> - defines the user name for an ROP client to
- login to an ROP server.</td>
- <td/>
- <td/>
- </tr>
- <tr>
- <td><code>cayenne.rop.service_password</code> - defines the password for an ROP client to login
- to an ROP server.</td>
- <td/>
- <td/>
- </tr>
- <tr>
- <td><code>cayenne.rop.shared_session_name</code>- defines the name of the shared session that
- an ROP client wants to join on an ROP server. If omitted, a dedicated
- session is created.</td>
- <td/>
- <td/>
- </tr>
- <tr>
- <td><code>cayenne.rop.service.timeout</code> - a value in milliseconds for the
- ROP client-server connection read operation timeout</td>
- <td>any positive long value</td>
- <td/>
- </tr>
- <tr>
- <td><code>cayenne.rop.channel_events</code> - defines whether client-side DataChannel should
- dispatch events to child ObjectContexts. If set to true, ObjectContexts will
- receive commit events and merge changes committed by peer contexts that
- passed through the common client DataChannel.</td>
- <td>true, false</td>
- <td>false</td>
- </tr>
- <tr>
- <td><code>cayenne.rop.context_change_events</code>- defines whether object property changes in
- the client context result in firing events. Client UI components can listen
- to these events and update the UI. Disabled by default.</td>
- <td>true, false</td>
- <td>false</td>
- </tr>
- <tr>
- <td><code>cayenne.rop.context_lifecycle_events</code> - defines whether object commit and
- rollback operations in the client context result in firing events. Client UI
- components can listen to these events and update the UI. Disabled by
- default.</td>
- <td>true,false</td>
- <td>false</td>
- </tr>
- <tr>
- <td><code>cayenne.server.rop_event_bridge_factory</code> - defines the name of
- the org.apache.cayenne.event.EventBridgeFactory that is passed from the ROP
- server to the client. I.e. server DI would provide a name of the factory,
- passing this name to the client via the wire. The client would instantiate
- it to receive events from the server. Note that this property is stored in
- "cayenne.server.rop_event_bridge_properties" map, not in the main
- "cayenne.properties".</td>
- <td/>
- <td/>
- </tr>
- </tbody>
- </table>
- </para>
-</appendix>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/appendix-b.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/appendix-b.xml b/docs/docbook/cayenne-guide/src/docbkx/appendix-b.xml
deleted file mode 100644
index cf0f035..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/appendix-b.xml
+++ /dev/null
@@ -1,100 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- 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.
--->
-<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="service-collections">
- <title>Service Collections</title>
- <para>Note that the collection keys below are
- defined as constants in <code>org.apache.cayenne.configuration.Constants</code>
- interface.</para>
- <para>
- <table frame="void">
- <caption>Service Collection Keys Present in ServerRuntime and/or ClientRuntime</caption>
- <col width="42%"/>
- <col width="25%"/>
- <col width="33%"/>
- <thead>
- <tr>
- <th>Collection Property</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>cayenne.properties</code></td>
- <td><code>Map<String,String></code></td>
- <td>Properties used by built-in
- Cayenne services. The keys in this map are the property names from the table
- in Appendix A. Separate copies of this map exist on the server and ROP
- client.</td>
- </tr>
- <tr>
- <td><code>cayenne.server.adapter_detectors</code></td>
- <td><code>List<DbAdapterDetector></code></td>
- <td>Contains
- objects that can discover the type of current database and install the
- correct DbAdapter in runtime.</td>
- </tr>
- <tr>
- <td><code>cayenne.server.domain_filters</code></td>
- <td><code>List<DataChannelFilter></code></td>
- <td>Stores DataDomain filters.</td>
- </tr>
- <tr>
- <td><code>cayenne.server.project_locations</code></td>
- <td><code>List<String></code></td>
- <td>Stores locations of the one of more project configuration files.</td>
- </tr>
- <tr>
- <td><code>cayenne.server.default_types</code></td>
- <td><code>List<ExtendedType></code></td>
- <td>Stores default adapter-agnostic ExtendedTypes. Default ExtendedTypes can be
- overridden / extended by DB-specific DbAdapters as well as by user-provided
- types configured in another colltecion (see
- <code>"cayenne.server.user_types"</code>).</td>
- </tr>
- <tr>
- <td><code>cayenne.server.user_types</code></td>
- <td><code>List<ExtendedType></code></td>
- <td>Stores a
- user-provided ExtendedTypes. This collection will be merged into a full list
- of ExtendedTypes and would override any ExtendedTypes defined in a default
- list, or by a DbAdapter.</td>
- </tr>
- <tr>
- <td><code>cayenne.server.type_factories</code></td>
- <td><code>List<ExtendedTypeFactory></code></td>
- <td>Stores default and user-provided ExtendedTypeFactories. ExtendedTypeFactory
- allows to define ExtendedTypes dynamically for the whole group of Java
- classes. E.g. Cayenne supplies a factory to map all Enums regardless of
- their type.</td>
- </tr>
- <tr>
- <td><code>cayenne.server.rop_event_bridge_properties</code></td>
- <td><code>Map<String, String></code></td>
- <td>Stores event bridge properties passed to the ROP client on
- bootstrap. This means that the map is configured by server DI, and passed to
- the client via the wire. The properties in this map are specific to
- EventBridgeFactory implementation (e.g JMS or XMPP connection prameters).
- One common property is <code>"cayenne.server.rop_event_bridge_factory"</code> that
- defines the type of the factory.</td>
- </tr>
- </tbody>
- </table>
- </para>
-
-</appendix>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/appendix-c.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/appendix-c.xml b/docs/docbook/cayenne-guide/src/docbkx/appendix-c.xml
deleted file mode 100644
index 8b036af..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/appendix-c.xml
+++ /dev/null
@@ -1,147 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- 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.
--->
-<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="expressions-bnf">
- <title>Expressions BNF</title>
- <para>
- <programlisting>
-TOKENS
-<DEFAULT> SKIP : {
-" "
-| "\t"
-| "\n"
-| "\r"
-}
-
-<DEFAULT> TOKEN : {
-<NULL: "null" | "NULL">
-| <TRUE: "true" | "TRUE">
-| <FALSE: "false" | "FALSE">
-}
-
-<DEFAULT> TOKEN : {
-<PROPERTY_PATH: <IDENTIFIER> ("." <IDENTIFIER>)*>
-}
-
-<DEFAULT> TOKEN : {
-<IDENTIFIER: <LETTER> (<LETTER> | <DIGIT>)* (["+"])?>
-| <#LETTER: ["_","a"-"z","A"-"Z"]>
-| <#DIGIT: ["0"-"9"]>
-}
-
-/**
- * Quoted Strings, whose object value is stored in the token manager's
- * "literalValue" field. Both single and double qoutes are allowed
- */<DEFAULT> MORE : {
-"\'" : WithinSingleQuoteLiteral
-| "\"" : WithinDoubleQuoteLiteral
-}
-
-<WithinSingleQuoteLiteral> MORE : {
-<ESC: "\\" (["n","r","t","b","f","\\","\'","`","\""] | (["0"-"3"])? ["0"-"7"] (["0"-"7"])?)> : {
-| <~["\'","\\"]> : {
-}
-
-<WithinSingleQuoteLiteral> TOKEN : {
-<SINGLE_QUOTED_STRING: "\'"> : DEFAULT
-}
-
-<WithinDoubleQuoteLiteral> MORE : {
-<STRING_ESC: <ESC>> : {
-| <~["\"","\\"]> : {
-}
-
-<WithinDoubleQuoteLiteral> TOKEN : {
-<DOUBLE_QUOTED_STRING: "\""> : DEFAULT
-}
-
-/**
- * Integer or real Numeric literal, whose object value is stored in the token manager's
- * "literalValue" field.
- */<DEFAULT> TOKEN : {
-<INT_LITERAL: ("0" (["0"-"7"])* | ["1"-"9"] (["0"-"9"])* | "0" ["x","X"] (["0"-"9","a"-"f","A"-"F"])+)
- (["l","L","h","H"])?> : {
-| <FLOAT_LITERAL: <DEC_FLT> (<EXPONENT>)? (<FLT_SUFF>)? | <DEC_DIGITS> <EXPONENT> (<FLT_SUFF>)?
-| <DEC_DIGITS> <FLT_SUFF>> : {
-| <#DEC_FLT: (["0"-"9"])+ "." (["0"-"9"])* | "." (["0"-"9"])+>
-| <#DEC_DIGITS: (["0"-"9"])+>
-| <#EXPONENT: ["e","E"] (["+","-"])? (["0"-"9"])+>
-| <#FLT_SUFF: ["d","D","f","F","b","B"]>
-}
-
-NON-TERMINALS
- expression := orCondition <EOF>
- orCondition := andCondition ( "or" andCondition )*
- andCondition := notCondition ( "and" notCondition )*
- notCondition := ( "not" | "!" ) simpleCondition
- | simpleCondition
- simpleCondition := <TRUE>
- | <FALSE>
- | scalarConditionExpression
- ( simpleNotCondition
- | ( "=" | "==" ) scalarExpression
- | ( "!=" | "<>" ) scalarExpression
- | "<=" scalarExpression
- | "<" scalarExpression | ">" scalarExpression
- | ">=" scalarExpression
- | "like" scalarExpression
- | "likeIgnoreCase" scalarExpression
- | "in" ( namedParameter | "(" scalarCommaList ")" )
- | "between" scalarExpression "and" scalarExpression
- )?
- simpleNotCondition := ( "not" | "!" )
- ( "like" scalarExpression
- | "likeIgnoreCase" scalarExpression
- | "in" ( namedParameter | "(" scalarCommaList ")" )
- | "between" scalarExpression "and" scalarExpression
- )
- scalarCommaList := ( scalarConstExpression ( "," scalarConstExpression )* )
- scalarConditionExpression := scalarNumericExpression
- | <SINGLE_QUOTED_STRING>
- | <DOUBLE_QUOTED_STRING>
- | <NULL>
- scalarExpression := scalarConditionExpression
- | <TRUE>
- | <FALSE>
- scalarConstExpression := <SINGLE_QUOTED_STRING>
- | <DOUBLE_QUOTED_STRING>
- | namedParameter
- | <INT_LITERAL>
- | <FLOAT_LITERAL>
- | <TRUE>
- | <FALSE>
- scalarNumericExpression := multiplySubtractExp
- ( "+" multiplySubtractExp | "-" multiplySubtractExp )*
- multiplySubtractExp := numericTerm ( "*" numericTerm | "/" numericTerm )*
- numericTerm := ( "+" )? numericPrimary
- | "-" numericPrimary
- numericPrimary := "(" orCondition ")"
- | pathExpression
- | namedParameter
- | <INT_LITERAL>
- | <FLOAT_LITERAL>
- namedParameter := "$" <PROPERTY_PATH>
- pathExpression := ( <PROPERTY_PATH>
- | "obj:" <PROPERTY_PATH>
- | "db:" <PROPERTY_PATH>
- | "enum:" <PROPERTY_PATH> )
-
-</programlisting>
- </para>
-
-
-</appendix>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml b/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml
deleted file mode 100644
index 6d76ef2..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml
+++ /dev/null
@@ -1,95 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- 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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="cayenne-mapping-structure">
- <title>Cayenne Mapping Structure</title>
- <section xml:id="cayenne-project">
- <title>Cayenne Project</title>
- <para>A Cayenne project is an XML representation of a model connecting database schema with
- Java classes. A project is normally created and manipulated via CayenneModeler GUI and
- then used to initialize Cayenne runtime. A project is made of one or more files. There's
- always a root project descriptor file in any valid project. It is normally called
- <code>cayenne-xyz.xml</code>, where "xyz" is the name of the project.</para>
- <para>Project descriptor can reference DataMap files, one per DataMap. DataMap files are
- normally called <code>xyz.map.xml</code>, where "xyz" is the name of the DataMap. For
- legacy reasons this naming convention is different from the convention for the root
- project descriptor above, and we may align it in the future versions. Here is how a
- typical project might look on the file
- system:<screen><prompt>$</prompt> <userinput>ls -l</userinput>
-total 24
--rw-r--r-- 1 cayenne staff 491 Jan 28 18:25 cayenne-project.xml
--rw-r--r-- 1 cayenne staff 313 Jan 28 18:25 datamap.map.xml</screen></para>
- <para>DataMap are referenced by name in the root
- descriptor:<programlisting language="xml"><map name="datamap"/></programlisting></para>
- <para>Map files are resolved by Cayenne by appending "<code>.map.xml</code>" extension to the
- map name, and resolving the resulting string relative to the root descriptor URI. The
- following sections discuss varios ORM model objects, without regards to their XML
- representation. XML format details are really unimportant to the Cayenne users.</para>
- </section>
- <section xml:id="datamap">
- <title>DataMap</title>
- <para>DataMap is a container of persistent entities and other object-relational metadata.
- DataMap provides developers with a scope to organize their entities, but it does not
- provide a namespace for entities. In fact all DataMaps present in runtime are combined
- in a single namespace. Each DataMap must be associated with a DataNode. This is how
- Cayenne knows which database to use when running a query.</para>
- </section>
- <section xml:id="datanode">
- <title>DataNode</title>
- <para>DataNode is model of a database. It is actually pretty simple. It has an arbitrary
- user-provided name and information needed to create or locate a JDBC DataSource. Most
- projects only have one DataNode, though there may be any number of nodes if
- needed.</para>
- </section>
- <section xml:id="dbentity">
- <title>DbEntity</title>
- <para>DbEntity is a model of a single DB table or view. DbEntity is made of DbAttributes
- that correspond to columns, and DbRelationships that map PK/FK pairs. DbRelationships
- are not strictly tied to FK constraints in DB, and should be mapped for all logical
- "relationships" between the tables.</para>
- </section>
- <section xml:id="objentity">
- <title>ObjEntity</title>
- <para>ObjEntity is a model of a single persistent Java class. ObjEntity is made of
- ObjAttributes and ObjRelationships. Both correspond to entity class properties. However
- ObjAttributes represent "simple" properties (normally things like String, numbers,
- dates, etc.), while ObjRelationships correspond to properties that have a type of
- another entity. </para>
- <para>ObjEntity maps to one or more DbEntities. There's always one "root" DbEntity for each
- ObjEntity. ObjAttribiute maps to a DbAttribute or an Embeddable. Most often mapped
- DbAttribute is from the root DbEntity. Sometimes mapping is done to a DbAttribute from
- another DbEntity somehow related to the root DbEntity. Such ObjAttribute is called
- "flattened". Similarly ObjRelationship maps either to a single DbRelationship, or to a
- chain of DbRelationships ("flattened" ObjRelationship).</para>
- <para>ObjEntities may also contain mapping of their lifecycle callback methods.</para>
- </section>
- <section xml:id="embeddable">
- <title>Embeddable</title>
- <para>Embeddable is a model of a Java class that acts as a single attribute of an ObjEntity,
- but maps to multiple columns in the database.</para>
- </section>
- <section xml:id="procedure">
- <title>Procedure</title>
- <para>A model of a stored procedure in the database.</para>
- </section>
- <section xml:id="query">
- <title>Query</title>
- <para>A model of a query. Cayenne allows queries to be mapped in Cayenne project, or created
- in the code. Depending on the circumstances the users may take one or the other
- approach.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml b/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml
deleted file mode 100644
index 4c6b9ae..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml
+++ /dev/null
@@ -1,116 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- 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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="cayennemodeler-application">
- <title>CayenneModeler Application</title>
- <section xml:id="working-with-mapping-projects">
- <title>Working with Mapping Projects</title>
- <para></para>
- </section>
- <section xml:id="reverse-engineering-database">
- <title>Reverse Engineering Database</title>
- <para>
- See chapter <link linkend="re-modeler">Reverse Engineering in Cayenne Modeler</link>
- </para>
- </section>
- <section xml:id="generating-database-schema">
- <title>Generating Database Schema</title>
- <para>
- With Cayenne Modeler you can create simple database schemas without any additional database tools.
- This is a good option for initial database setup if you completely created you model with the Modeler.
- You can start SQL schema generation by selecting menu
- <emphasis role="strong">
- <guimenu>Tools</guimenu> > <guimenuitem>Generate Database Schema</guimenuitem>
- </emphasis>
- </para>
- <para>
- You can select what database parts should be generated and what tables you want
- </para>
- </section>
- <section xml:id="migrations">
- <title>Migrations</title>
- <para> </para>
- </section>
- <section xml:id="generating-java-classes">
- <title>Generating Java Classes</title>
- <para>
- Before using Cayenne in you code you need to generate java source code for persistent objects.
- This can be done with Modeler GUI or via <link linkend="mvn-cgen">cgen</link> maven/ant plugin.
- </para>
- <para>
- To generate classes in the modeler use
- <emphasis role="strong">
- <guimenu>Tools</guimenu> > <guimenuitem>Generate Classes</guimenuitem>
- </emphasis>
- </para>
- <para>
- There is three default types of code generation
- <itemizedlist>
- <listitem>
- <para><emphasis role="strong">Standard Persistent Objects</emphasis></para>
- <para>
- Default type of generation suitable for almost all cases.
- Use this type unless you now what exactly you need to customize.
- </para>
- </listitem>
- <listitem>
- <para><emphasis role="strong">Client Persistent Objects</emphasis></para>
- <para>
-
- </para>
- </listitem>
- <listitem>
- <para><emphasis role="strong">Advanced.</emphasis></para>
- <para>
- In advanced mode you can control almost all aspects of code generation including custom templates for java code.
- See default Cayenne templates on
- <link xlink:href="https://github.com/apache/cayenne/tree/master/cayenne-tools/src/main/resources/templates/v1_2">GitHub</link>
- as an example
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
- <section xml:id="modeling-inheritance">
- <title>Modeling Inheritance</title>
- <para> </para>
- </section>
- <section xml:id="modeling-generic-persistence-classes">
- <title>Modeling Generic Persistent Classes</title>
- <para>Normally each ObjEntity is mapped to a specific Java class (such as Artist or
- Painting) that explicitly declare all entity properties as pairs of getters and setters.
- However Cayenne allows to map a completly generic class to any number of entities. The
- only expectation is that a generic class implements
- <emphasis>org.apache.cayenne.DataObject</emphasis>. So an ideal candidate for a
- generic class is CayenneDataObject, or some custom subclass of CayenneDataObject.</para>
- <para>If you don't enter anything for Java Class of an ObjEntity, Cayenne assumes generic
- mapping and uses the following implicit rules to determine a class of a generic object.
- If DataMap "Custom Superclass" is set, runtime uses this class to instantiate new
- objects. If not, org.apache.cayenne.CayenneDataObject is used.</para>
- <para>Class generation procedures (either done in the Modeler or with Ant or Maven) would
- skip entities that are mapped to CayenneDataObject explicitly or have no class
- mapping.</para>
- </section>
- <section xml:id="mapping-objattributes-to-custom-classes">
- <title>Mapping ObjAttributes to Custom Classes</title>
- <para> </para>
- </section>
- <section xml:id="modeling-pk-generation-strategy">
- <title>Modeling Primary Key Generation Strategy</title>
- <para> </para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/current-limitations.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/current-limitations.xml b/docs/docbook/cayenne-guide/src/docbkx/current-limitations.xml
deleted file mode 100644
index 4b69324..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/current-limitations.xml
+++ /dev/null
@@ -1,20 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- 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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="current-limitations">
- <title>Current Limitations</title>
-</chapter>