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/04 16:01:18 UTC
[04/14] cayenne git commit: Switch documentation from Docbook to
Asciidoctor format
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/cayenne-guide/src/docbkx/queries-sqltemplate.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/queries-sqltemplate.xml b/docs/docbook/cayenne-guide/src/docbkx/queries-sqltemplate.xml
deleted file mode 100644
index bbfa559..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/queries-sqltemplate.xml
+++ /dev/null
@@ -1,396 +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.
--->
-<section xmlns="http://docbook.org/ns/docbook" xml:id="sqltemplate">
- <title>SQLTemplate</title>
- <para>SQLTemplate is a query that allows to run native SQL from a Cayenne application. It
- comes handy when the standard ORM concepts are not sufficient for a given query or an
- update. SQL is too powerful and allows to manipulate data in ways that are not easily
- described as a graph of related entities. Cayenne acknowledges this fact and provides
- this facility to execute SQL, mapping the result to objects when possible. Here are
- examples of selecting and non-selecting
- SQLTemplates:<programlisting language="java">SQLTemplate select = new SQLTemplate(Artist.class, "select * from ARTIST");
-List<Artist> result = context.performQuery(select);</programlisting><programlisting language="java">SQLTemplate update = new SQLTemplate(Artist.class, "delete from ARTIST");
-QueryResponse response = context.performGenericQuery(update);</programlisting></para>
- <para>Cayenne doesn't make any attempt to make sense of the SQL semantics, so it doesn't
- know whether a given query is performing a select or update, etc. It is the the user's
- decision to run a given query as a selecting or "generic".</para>
- <para>
- <note>
- <para>Any data modifications done to DB as a result of SQLTemplate execution do not
- change the state of objects in the ObjectContext. So some objects in the context
- may become stale as a result.</para>
- </note>
- </para>
- <para>Another point to note is that the first argument to the SQLTemplate constructor - the
- Java class - has the same meaning as in SelectQuery only when the result can be
- converted to objects (e.g. when this is a selecting query and it is selecting all
- columns from one table). In this case it denotes the "root" entity of this query result.
- If the query does not denote a single entity result, this argument is only used for
- query routing, i.e. determining which database it should be run against. You are free to
- use any persistent class or even a DataMap instance in such situation. It will work as
- long as the passed "root" maps to the same database as the current query.</para>
- <para>To achieve interoperability between mutliple RDBMS a user can specify multiple SQL
- statements for the same SQLTemplate, each corresponding to a native SQL dialect. A key
- used to look up the right dialect during execution is a fully qualified class name of
- the corresponding DbAdapter. If no DB-specific statement is present for a given DB, a
- default generic statement is used. E.g. in all the examples above a default statement
- will be used regardless of the runtime database. So in most cases you won't need to
- explicitly "translate" your SQL to all possible dialects. Here is how this works in
- practice:<programlisting language="java">SQLTemplate select = new SQLTemplate(Artist.class, "select * from ARTIST");
-
-// For Postgres it would be nice to trim padding of all CHAR columns.
-// Otherwise those will be returned with whitespace on the right.
-// assuming "NAME" is defined as CHAR...
-String pgSQL = "SELECT ARTIST_ID, RTRIM(NAME), DATE_OF_BIRTH FROM ARTIST";
-query.setTemplate(PostgresAdapter.class.getName(), pgSQL);</programlisting></para>
-
- <section xml:id="sqltemplate-scripting">
- <title>Scripting SQLTemplate with Velocity</title>
- <para>The most interesting aspect of SQLTemplate (and the reason why it is called a
- "template") is that a SQL string is treated by Cayenne as an Apache Velocity
- template. Before sending it to DB as a PreparedStatement, the String is evaluated in
- the Velocity context, that does variable substitutions, and performs special
- callbacks in response to various directives, thus controlling query interaction with
- the JDBC layer. </para>
- <para>Check Velocity docs for the syntax details. Here we'll just mention the two main
- scripting elements - "variables" (that look like <code>$var</code>) and "directives"
- (that look like <code>#directive(p1 p2 p3)</code>). All built-in Velocity directives
- are supported. Additionally Cayenne defines a number of its own directives to bind
- parameters to PreparedStatements and to control the structure of the ResultSet.
- These directives are described in the following sections.</para>
- </section>
- <section xml:id="sqltemplate-parameters">
- <title>Variable Substitution</title>
- <para>All variables in the template string are replaced from query
- parameters:<programlisting language="java">SQLTemplate query = new SQLTemplate(Artist.class, "delete from $tableName");
-query.setParameters(Collections.singletonMap("tableName", "mydb.PAINTING"));
-
-// this will generate SQL like this: "delete from mydb.PAINTING"</programlisting>The
- example above demonstrates the point made earlier in this chapter - even if we don't
- know upfront which table the query will run against, we can still use a fixed "root"
- in constructor (<code>Artist.class</code> in this case) , as we are not planning on
- converting the result to objects.</para>
- <para>Variable substitution within the text uses "<code>object.toString()</code>" method to replace the
- variable value. Keep in mind that this may not be appropriate in all situations.
- E.g. passing a date object in a WHERE clause expression may be converted to a String
- not understood by the target RDBMS SQL parser. In such cases variable should be wrapped in <code>#bind</code>
- directive as described below.</para>
- </section>
- <section xml:id="sqltemplate-bind-directive">
- <title>Directives</title>
- <para>These are the Cayenne directives used to customize SQLTemplate parsing and
- integrate it with the JDBC layer: </para>
- <section>
- <title>#bind</title>
- <para>Creates a PreparedStatement positional parameter in place of the directive,
- binding the value to it before statement execution. <code>#bind</code> is
- allowed in places where a "?" would be allowed in a PreparedStatement. And in
- such places it almost always makes sense to pass objects to the template via
- this or other forms of <code>#bind</code> instead of inserting them
- inline.</para>
- <para><emphasis role="italic">Semantics:</emphasis></para>
- <programlisting language="java">#bind(value)
-#bind(value jdbcType)
-#bind(value jdbcType scale)</programlisting>
- <para><emphasis role="italic">Arguments:</emphasis>
- <itemizedlist>
- <listitem>
- <para><code>value</code> - can either be a char constant or a variable
- that is resolved from the query parameters. Note that the variable
- can be a collection, that will be automatically expanded into a list
- of individual value bindings. This is useful for instance to build
- IN conditions. </para>
- </listitem>
- <listitem>
- <para><code>jdbcType</code> - is a JDBC data type of the parameter as
- defined in <code>java.sql.Types</code>.</para>
- </listitem>
- <listitem>
- <para><code>scale</code> - An optional scale of the numeric value. Same
- as "scale" in PreparedStatement.</para>
- </listitem>
- </itemizedlist></para>
- <para>
- <emphasis role="italic"
- >Usage</emphasis>:<programlisting language="java">#bind($xyz)
-#bind('str')
-#bind($xyz 'VARCHAR')
-#bind($xyz 'DECIMAL' 2)</programlisting></para>
- <para><emphasis role="italic">Full
- example:</emphasis><programlisting language="sql">update ARTIST set NAME = #bind($name) where ID = #bind($id)</programlisting></para>
- </section>
- <section>
- <title>#bindEqual</title>
- <para>Same as #bind, but also includes the "=" sign in front of the value binding.
- Look at the example below - we took the #bind example and replaced "<code>ID =
- #bind(..)</code>" with "<code>ID #bindEqual(..)</code>". While it looks like
- a clumsy shortcut to eliminate the equal sign, the actual reason why this is
- useful is that it allows the value to be null. If the value is not null,
- "<code>= ?</code>" is generated, but if it is, the resulting chunk of the
- SQL would look like "<code>IS NULL</code>" and will be compilant with what the
- DB expects.</para>
- <para><emphasis role="italic">Semantics:</emphasis></para>
- <programlisting language="java">#bindEqual(value)
-#bindEqual(value jdbcType)
-#bindEqual(value jdbcType scale)</programlisting>
- <para><emphasis role="italic">Arguments: (same as #bind)</emphasis>
- </para>
- <para>
- <emphasis role="italic"
- >Usage</emphasis>:<programlisting language="java">#bindEqual($xyz)
-#bindEqual('str')
-#bindEqual($xyz 'VARCHAR')
-#bindEqual($xyz 'DECIMAL' 2)</programlisting></para>
- <para><emphasis role="italic">Full
- example:</emphasis><programlisting language="sql">update ARTIST set NAME = #bind($name) where ID #bindEqual($id)</programlisting></para>
- </section>
- <section>
- <title>#bindNotEqual</title>
- <para>This directive deals with the same issue as <code>#bindEqual</code> above,
- only it generates "not equal" in front of the value (or IS NOT NULL).</para>
- <para><emphasis role="italic">Semantics:</emphasis></para>
- <programlisting language="java">#bindNotEqual(value)
-#bindNotEqual(value jdbcType)
-#bindNotEqual(value jdbcType scale)</programlisting>
- <para><emphasis role="italic">Arguments: (same as #bind)</emphasis></para>
- <para>
- <emphasis role="italic"
- >Usage</emphasis>:<programlisting language="java">#bindNotEqual($xyz)
-#bindNotEqual('str')
-#bindNotEqual($xyz 'VARCHAR')
-#bindNotEqual($xyz 'DECIMAL' 2)</programlisting></para>
- <para><emphasis role="italic">Full
- example:</emphasis><programlisting language="sql">update ARTIST set NAME = #bind($name) where ID #bindEqual($id)</programlisting></para>
- </section>
- <section>
- <title>#bindObjectEqual</title>
- <para>It can be tricky to use a Persistent object or an ObjectId in a binding,
- especially for tables with compound primary keys. This directive helps to handle
- such binding. It maps columns in the query to the names of Persistent object ID
- columns, extracts ID values from the object, and generates SQL like "COL1 = ?
- AND COL2 = ? ..." , binding positional parameters to ID values. It can also
- correctly handle null object. Also notice how we are specifying a Velocity array
- for multi-column PK.</para>
- <para><emphasis role="italic">Semantics:</emphasis></para>
- <programlisting language="java">#bindObjectEqual(value columns idColumns)</programlisting>
- <para><emphasis role="italic">Arguments:</emphasis>
- <itemizedlist>
- <listitem>
- <para><code>value</code> - must be a variable that is resolved from the
- query parameters to a Persistent or ObjectId.</para>
- </listitem>
- <listitem>
- <para><code>columns</code> - the names of the columns to generate in the
- SQL.</para>
- </listitem>
- <listitem>
- <para><code>idColumn</code> - the names of the ID columns for a given
- entity. Must match the order of "columns" to match against.</para>
- </listitem>
- </itemizedlist></para>
- <para>
- <emphasis role="italic"
- >Usage</emphasis>:<programlisting language="java">#bindObjectEqual($a 't0.ID' 'ID')
-#bindObjectEqual($b ['t0.FK1', 't0.FK2'] ['PK1', 'PK2'])</programlisting></para>
- <para><emphasis role="italic">Full
- example:</emphasis><programlisting language="java">String sql = "SELECT * FROM PAINTING t0 WHERE #bindObjectEqual($a 't0.ARTIST_ID' 'ARTIST_ID' ) ORDER BY PAINTING_ID";
-SQLTemplate select = new SQLTemplate(Artist.class, sql);
-
-Artist a = ....
-select.setParameters(Collections.singletonMap("a", a)); </programlisting></para>
- </section>
- <section>
- <title>#bindObjectNotEqual</title>
- <para>Same as #bindObjectEqual above, only generates "not equal" operator for value
- comparison (or IS NOT NULL).</para>
- <para><emphasis role="italic">Semantics:</emphasis></para>
- <programlisting language="java">#bindObjectNotEqual(value columns idColumns)</programlisting>
- <para><emphasis role="italic">Arguments: (same as #bindObjectEqual)</emphasis>
- </para>
- <para>
- <emphasis role="italic"
- >Usage</emphasis>:<programlisting language="java">#bindObjectNotEqual($a 't0.ID' 'ID')
-#bindObjectNotEqual($b ['t0.FK1', 't0.FK2'] ['PK1', 'PK2'])</programlisting></para>
- <para><emphasis role="italic">Full
- example:</emphasis><programlisting language="java">String sql = "SELECT * FROM PAINTING t0 WHERE #bindObjectNotEqual($a 't0.ARTIST_ID' 'ARTIST_ID' ) ORDER BY PAINTING_ID";
-SQLTemplate select = new SQLTemplate(Artist.class, sql);
-
-Artist a = ....
-select.setParameters(Collections.singletonMap("a", a)); </programlisting></para>
- </section>
- <section>
- <title>#result</title>
- <para>Renders a column in SELECT clause of a query and maps it to a key in the
- result DataRow. Also ensures the value read is of the correct type. This allows
- to create a DataRow (and ultimately - a persistent object) from an arbitrary
- ResultSet.</para>
- <para><emphasis role="italic">Semantics:</emphasis></para>
- <programlisting language="java">#result(column)
-#result(column javaType)
-#result(column javaType alias)
-#result(column javaType alias dataRowKey)</programlisting>
- <para><emphasis role="italic">Arguments:</emphasis>
- <itemizedlist>
- <listitem>
- <para><code>column</code> - the name of the column to render in SQL
- SELECT clause.</para>
- </listitem>
- <listitem>
- <para><code>javaType</code> - a fully-qualified Java class name for a
- given result column. For simplicity most common Java types used in
- JDBC can be specified without a package. These include all numeric
- types, primitives, String, SQL dates, BigDecimal and BigInteger. So
- "<code>#result('A' 'String')</code>", "<code>#result('B'
- 'java.lang.String')</code>" and "<code>#result('C'
- 'int')</code>" are all valid</para>
- </listitem>
- <listitem>
- <para><code>alias</code> - specifies both the SQL alias of the column
- and the value key in the DataRow. If omitted, "column" value is
- used.</para>
- </listitem>
- <listitem>
- <para><code>dataRowKey</code> - needed if SQL 'alias' is not appropriate
- as a DataRow key on the Cayenne side. One common case when this
- happens is when a DataRow retrieved from a query is mapped using
- joint prefetch keys (see below). In this case DataRow must use
- database path expressions for joint column keys, and their format is
- incompatible with most databases alias format. </para>
- </listitem>
- </itemizedlist></para>
- <para>
- <emphasis role="italic"
- >Usage</emphasis>:<programlisting language="java">#result('NAME')
-#result('DATE_OF_BIRTH' 'java.util.Date')
-#result('DOB' 'java.util.Date' 'DATE_OF_BIRTH')
-#result('DOB' 'java.util.Date' '' 'artist.DATE_OF_BIRTH')
-#result('SALARY' 'float') </programlisting></para>
- <para><emphasis role="italic">Full
- example:</emphasis><programlisting language="sql">SELECT #result('ID' 'int'), #result('NAME' 'String'), #result('DATE_OF_BIRTH' 'java.util.Date') FROM ARTIST</programlisting></para>
- <note>
- <para>For advanced features you may look at the <link linkend="ext-velocity">Apache Velocity extension</link></para>
- </note>
- </section>
- </section>
- <section>
- <title>Mapping SQLTemplate Results</title>
- <para>Here we'll discuss how to convert the data selected via SQLTemplate to some
- useable format, compatible with other query results. It can either be very simple or
- very complex, depending on the structure of the SQL, JDBC driver nature and the
- desired result structure. This section presents various tips and tricks dealing with
- result mapping. </para>
- <para>By default SQLTemplate is expected to return a List of Persistent objects of its
- root type. This is the simple
- case:<programlisting language="java">SQLTemplate query = new SQLTemplate(Artist.class, "SELECT * FROM ARTIST");
-
-// List of Artists
-List<Artist> artists = context.performQuery(query);</programlisting>Just
- like SelectQuery, SQLTemplate can fetch DataRows. In fact DataRows option is very
- useful with SQLTemplate, as the result type most often than not does not represent a
- Cayenne entity, but instead may be some aggregated report or any other data whose
- object structure is opaque to
- Cayenne:<programlisting language="java">String sql = "SELECT t0.NAME, COUNT(1) FROM ARTIST t0 JOIN PAINTING t1 ON (t0.ID = t1.ARTIST_ID) "
- + "GROUP BY t0.NAME ORDER BY COUNT(1)";
-SQLTemplate query = new SQLTemplate(Artist.class, sql);
-
-// ensure we are fetching DataRows
-query.setFetchingDataRows(true);
-
-// List of DataRow
-List<DataRow> rows = context.performQuery(query);</programlisting>In
- the example above, even though the query root is Artist. the result is a list of
- artist names with painting counts (as mentioned before in such case "root" is only
- used to find the DB to fetch against, but has no bearning on the result). The
- DataRows here are the most appropriate and desired result type.</para>
- <para>In a more advanced case you may decide to fetch a list of scalars or a list of
- Object[] with each array entry being either an entity or a scalar. You probably
- won't be doing this too often and it requires quite a lot of work to setup, but if
- you want your SQLTemplate to return results similar to EJBQLQuery, it is doable
- using SQLResult as described
- below:<programlisting language="java">SQLTemplate query = new SQLTemplate(Painting.class, "SELECT ESTIMATED_PRICE P FROM PAINTING");
-
-// let Cayenne know that result is a scalar
-SQLResult resultDescriptor = new SQLResult();
-resultDescriptor.addColumnResult("P");
-query.setResult(resultDescriptor);
-
-// List of BigDecimals
-List<BigDecimal> prices = context.performQuery(query); </programlisting><programlisting language="java">SQLTemplate query = new SQLTemplate(Artist.class, "SELECT t0.ID, t0.NAME, t0.DATE_OF_BIRTH, COUNT(t1.PAINTING_ID) C " +
- "FROM ARTIST t0 LEFT JOIN PAINTING t1 ON (t0.ID = t1.ARTIST_ID) " +
- "GROUP BY t0.ID, t0.NAME, t0.DATE_OF_BIRTH");
-
-// let Cayenne know that result is a mix of Artist objects and the count of their paintings
-EntityResult artistResult = new EntityResult(Artist.class);
-artistResult.addDbField(Artist.ID_PK_COLUMN, "ARTIST_ID");
-artistResult.addObjectField(Artist.NAME_PROPERTY, "NAME");
-artistResult.addObjectField(Artist.DATE_OF_BIRTH_PROPERTY, "DATE_OF_BIRTH");
-
-SQLResult resultDescriptor = new SQLResult();
-resultDescriptor.addEntityResult(artistResult);
-resultDescriptor.addColumnResult("C");
-query.setResult(resultDescriptor);
-
-// List of Object[]
-List<Object[]> data = context.performQuery(query);</programlisting></para>
- <para>Another trick related to mapping result sets is making Cayenne recognize
- prefetched entities in the result set. This emulates "joint" prefetching of
- SelectQuery, and is achieved by special column naming. Columns belonging to the
- "root" entity of the query should use unqualified names corresponding to the root
- DbEntity columns. For each related entity column names must be prefixed with
- relationship name and a dot (e.g. "toArtist.ID"). Column naming can be controlled
- with "#result"
- directive:<programlisting language="java">String sql = "SELECT distinct "
- + "#result('t1.ESTIMATED_PRICE' 'BigDecimal' '' 'paintings.ESTIMATED_PRICE'), "
- + "#result('t1.PAINTING_TITLE' 'String' '' 'paintings.PAINTING_TITLE'), "
- + "#result('t1.GALLERY_ID' 'int' '' 'paintings.GALLERY_ID'), "
- + "#result('t1.ID' 'int' '' 'paintings.ID'), "
- + "#result('NAME' 'String'), "
- + "#result('DATE_OF_BIRTH' 'java.util.Date'), "
- + "#result('t0.ID' 'int' '' 'ID') "
- + "FROM ARTIST t0, PAINTING t1 "
- + "WHERE t0.ID = t1.ARTIST_ID";
-
-SQLTemplate q = new SQLTemplate(Artist.class, sql);
-q.addPrefetch(Artist.PAINTINGS_PROPERTY)
-List<Artist> objects = context.performQuery(query);</programlisting></para>
- <para>And the final tip deals with capitalization of the DataRow keys. Queries like
- "<code>SELECT * FROM...</code>" and even "<code>SELECT COLUMN1, COLUMN2, ...
- FROM ...</code>" can sometimes result in Cayenne exceptions on attempts to
- convert fetched DataRows to objects. Essentially any query that is not using a
- <code>#result</code> directive to describe the result set is prone to this
- problem, as different databases may produce different capitalization of the
- java.sql.ResultSet columns. </para>
- <para>The most universal way to address this issue is to describe each column explicitly
- in the SQLTemplate via <code>#result</code>, e.g.: "<code>SELECT #result('column1'),
- #result('column2'), ..</code>". However this quickly becomes impractical for
- tables with lots of columns. For such cases Cayenne provides a shortcut based on the
- fact that an ORM mapping usually follows some naming convention for the column
- names. Simply put, for case-insensitive databases developers normally use either all
- lowercase or all uppercase column names. Here is the API that takes advantage of
- that user knowledge and forces Cayenne to follow a given naming convention for the
- DataRow keys (this is also available as a dropdown in the
- Modeler):<programlisting language="java">SQLTemplate query = new SQLTemplate("SELECT * FROM ARTIST");
-query.setColumnNamesCapitalization(CapsStrategy.LOWER);
-List objects = context.performQuery(query);</programlisting></para>
- <para>or<programlisting language="java">SQLTemplate query = new SQLTemplate("SELECT * FROM ARTIST");
-query.setColumnNamesCapitalization(CapsStrategy.UPPER);
-List objects = context.performQuery(query); </programlisting></para>
- <para>None of this affects the generated SQL, but the resulting DataRows are using
- correct capitalization. Note that you probably shouldn't bother with this unless you
- are getting CayenneRuntimeExceptions when fetching with SQLTemplate.</para>
- </section>
- </section>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/cayenne-guide/src/docbkx/queries.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/queries.xml b/docs/docbook/cayenne-guide/src/docbkx/queries.xml
deleted file mode 100644
index 28b2993..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/queries.xml
+++ /dev/null
@@ -1,55 +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:xi="http://www.w3.org/2001/XInclude"
- version="5.0" xml:id="queries">
- <title>Queries</title>
- <para>Queries are Java objects used by the application to communicate with the database. Cayenne
- knows how to translate queries into SQL statements appropriate for a particular database
- engine. Most often queries are used to find objects matching certain criteria, but there are
- other types of queries too. E.g. those allowing to run native SQL, call DB stored
- procedures, etc. When committing objects, Cayenne itself creates special queries to
- insert/update/delete rows in the database. </para>
- <para>There is a number of built-in queries in Cayenne, described later in this chapter. Most of
- the newer queries use fluent API and can be created and executed as easy-to-read one-liners.
- Users can define their own query types to abstract certain DB interactions that for whatever
- reason can not be adequately described by the built-in set.</para>
- <para>Queries can be roughly categorized as "object" and "native". Object queries (most notably
- ObjectSelect, SelectById, and EJBQLQuery) are built with abstractions originating in the
- object model (the "object" side in the "object-relational" divide). E.g. ObjectSelect is
- assembled from a Java class of the objects to fetch, a qualifier expression, orderings, etc.
- - all of this expressed in terms of the object model.</para>
- <para>Native queries describe a desired DB operation as SQL code (SQLSelect, SQLTemplate query)
- or a reference to a stored procedure (ProcedureQuery), etc. The results of native queries
- are usually presented as Lists of Maps, with each map representing a row in the DB (a term
- "data row" is often used to describe such a map). They can potentially be converted to
- objects, however it may take a considerable effort to do so. Native queries are also less
- (if at all) portable across databases than object queries. </para>
-
- <xi:include href="queries-select.xml"/>
- <xi:include href="queries-ejbql.xml"/>
- <xi:include href="queries-selectbyid.xml"/>
- <xi:include href="queries-sqlselect.xml"/>
- <xi:include href="queries-mapped.xml"/>
- <xi:include href="queries-procedurecall.xml"/>
- <xi:include href="queries-custom.xml"/>
- <xi:include href="queries-sqltemplate.xml"/>
-
- <!-- ProcedureQuery is not deprecated as of 4.0 but newer ProcedureCall is preferred -->
- <!--<xi:include href="queries-procedure.xml"/>-->
- <!-- NamedQuery deprecated since 4.0 -->
- <!--<xi:include href="queries-namedquery.xml"/>-->
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/cayenne-guide/src/docbkx/re-filtering.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/re-filtering.xml b/docs/docbook/cayenne-guide/src/docbkx/re-filtering.xml
deleted file mode 100644
index a54ac2f..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/re-filtering.xml
+++ /dev/null
@@ -1,356 +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="re-filtering">
- <title>Filtering</title>
- <para>
- The first thing you usually want to control during reverse engineering is what exactly should be loaded from database and
- what not. One of the most common cases is excluding system tables, as you usually don't want to map them.
- </para>
- <para>
- Briefly, you are able to include/exclude tables, columns and procedures and do it at several levels: default, catalog, schema.
- Although everything defined at the top level (default rules) will be applied for the nested elements, all rules from the most specific
- areas will override general rules (i.e. rules from schemas override rules from catalogs and even more override default rules).
- </para>
- <para>
- The following use-cases will provide you a better understanding of how filtering works and how you could use it.
- </para>
- <section xml:id="everything-schema-catalog">
- <title>Process everything from schema/catalog</title>
- <para>
- The simplest example of reverse engineering is processing tables from one schema of catalog and there are several options to do this.
- Basic syntax is described below:
- </para>
- <programlisting language="xml"><dbimport>
- <!-- Ant/Maven in case you only want to specify the schema to import -->
- <schema>SCHEMA_NAME</schema>
-
- <!-- Maven way in case you have nested elements in the schema -->
- <schema>
- <name>SCHEMA_NAME</name>
- ...
- </schema>
-
- <!-- Ant way in case you have nested elements in the schema -->
- <schema name="SCHEMA_NAME">
- ...
- </schema>
-</dbimport> </programlisting>
- <para>
- The same options are available for catalogs:
- </para>
- <programlisting language="xml"> <dbimport>
- <!-- Ant/Maven in case you only want to specify the catalog to import -->
- <catalog>CATALOG_NAME</catalog>
-
- <!-- Maven way in case you have nested elements in the catalog -->
- <catalog>
- <name>CATALOG_NAME</name>
- ...
- </catalog>
-
- <!-- Ant way in case you have nested elements in the catalog -->
- <catalog name="CATALOG_NAME">
- ...
- </catalog>
-</dbimport></programlisting>
- <note>
- <para>Current version of reverse engineering doesn't support catalog filtering for Postgres database.</para>
- </note>
- </section>
- <section xml:id="combine-schema-catalog">
- <title>Combine Schema and Catalog filters</title>
- <para>
- Cayenne supports combination of different schemas and catalogs, and it filters data according to your requirements.
- You could achieve this by the following example of reverse engineering configuration:
- </para>
- <programlisting language="xml"><dbimport>
-
- <catalog>
- <name>shop_01</name>
- <schema>schema-name-01</schema>
- <schema>schema-name-02</schema>
- <schema>schema-name-03</schema>
- </catalog>
-
- <catalog>
- <name>shop_02</name>
- <schema>schema-name-01</schema>
- </catalog>
-
- <catalog>
- <name>shop_03</name>
- <schema>schema-name-01</schema>
- <schema>schema-name-02</schema>
- <schema>schema-name-03</schema>
- </catalog>
-
-</dbimport></programlisting>
- <para>
- In the example above, Cayenne reverse engineering process contains three catalogs named as shop_01, shop_02 and shop_03,
- each of wich has their own schemas. Cayenne will load all data only from the declared catalogs and schemas.
- </para>
- <para>
- If you want to load everything from database, you could simply declare catalog specification alone.
- </para>
- <programlisting language="xml"><dbimport>
-
- <catalog>shop_01</catalog>
- <catalog>shop_02</catalog>
- <catalog>shop_03</catalog>
-
-</dbimport></programlisting>
- <para>
- If you want to do reverse engineering for specific schemas, just remove unwanted schemas from the catalog section.
- For example, if you want to process schema-name-01 and schema-name-03 schemas only, then you should change reverse engineering section like this.
- </para>
- <programlisting language="xml"><dbimport>
-
- <catalog>
- <name>shop_01</name>
- <schema>schema-name-01</schema>
- <schema>schema-name-03</schema>
- </catalog>
-
- <catalog>
- <name>shop_02</name>
- <schema>schema-name-01</schema>
- </catalog>
-
- <catalog>
- <name>shop_03</name>
- <schema>schema-name-01</schema>
- <schema>schema-name-03</schema>
- </catalog>
-
-</dbimport></programlisting>
- </section>
- <section xml:id="including-excluding-tables-columns-procedures">
- <title>Including and Excluding tables, columns and procedures</title>
- <para>
- Cayenne reverse engineering let you fine tune table, columns and stored procedures names that you need to import
- to your model file. In every filter you can use regexp syntax. Here is some examples of configuration
- for common tasks.
- </para>
- <para>
- <orderedlist numeration="arabic">
- <listitem>
- <para>Include tables with ‘CRM_’ prefix if you are working in that domain of application:</para>
- <programlisting language="xml"><includeTable>CRM_.*</includeTable></programlisting>
- </listitem>
- <listitem>
- <para>Include tables with ‘_LOOKUP’ suffix</para>
- <programlisting language="xml"><includeTable>
- <pattern>.*_LOOKUP</pattern>
-</includeTable></programlisting>
- </listitem>
- <listitem>
- <para>Exclude tables with ‘CRM_’ prefix if you are not working only in that domain of application:</para>
- <programlisting language="xml"><excludeTable>CRM_.*</excludeTable></programlisting>
- </listitem>
- <listitem>
- <para>Include only specific columns that follows specific naming convention:</para>
- <programlisting language="xml"><includeColumn>includeColumn01</includeColumn>
-<includeColumn>includeColumn03</includeColumn></programlisting>
- </listitem>
- <listitem>
- <para>Exclude system or obsolete columns:</para>
- <programlisting language="xml"><excludeColumn>excludeColumn01</excludeColumn>
-<excludeColumn>excludeColumn03</excludeColumn></programlisting>
- </listitem>
- <listitem>
- <para>Include/Exclude columns for particular table or group of tables:</para>
- <programlisting language="xml"><includeTable>
- <pattern>table pattern</pattern>
- <includeColumn>includeColumn01</includeColumn>
- <excludeColumn>excludeColumn01</excludeColumn>
-</includeTable></programlisting>
- </listitem>
- <listitem>
- <para>Include stored procedures:</para>
- <programlisting language="xml"><includeProcedure>includeProcedure01</includeProcedure>
-<includeProcedure>
- <pattern>includeProcedure03</pattern>
-</includeProcedure></programlisting>
- </listitem>
- <listitem>
- <para>Exclude stored procedures by pattern:</para>
- <programlisting language="xml"><excludeProcedure>excludeProcedure01</excludeProcedure>
-<excludeProcedure>
- <pattern>excludeProcedure03</pattern>
-</excludeProcedure></programlisting>
- </listitem>
- </orderedlist>
- </para>
- <para> All filtering tags <code><includeTable></code>,
- <code><excludeTable></code>, <code><includeColumn></code>,
- <code><excludeColumn></code>, <code><includeProcedure></code> and
- <code><excludeProcedure></code> have 2 ways to pass filtering RegExp.
- <orderedlist numeration="arabic">
- <listitem>
- <para>text inside tag</para>
- <programlisting language="xml">
- <includeTable>CRM_.*</includeTable></programlisting>
- </listitem>
- <listitem>
- <para>pattern inner tag</para>
- <programlisting language="xml">
- <includeTable>
- <pattern>.*_LOOKUP</pattern>
- </includeTable></programlisting>
- </listitem>
- </orderedlist>
- </para>
- <para>
- All filtering tags can be placed inside schema and catalog tags, but also inside <code><dbimport></code> tag. It means that filtering rules
- will be applied for all schemas and catalogs.
- </para>
- </section>
- <section xml:id="complete-filtering-example">
- <title>Complete filtering example</title>
- <para>
- Initially, let’s make a small sample. Consider the following reverse engineering configuration.
- </para>
- <programlisting language="xml"><dbimport>
- <catalog>shop-01</catalog>
-</dbimport> </programlisting>
- <para>
- In this case reverse engineering will not filter anything from the shop-01 catalog. If you really want to filter database columns, tables,
- stored procedures and relationships, you could do it in the following way.
- </para>
- <programlisting language="xml"><dbimport>
- <catalog>shop-01</catalog>
- <catalog>
- <name>shop-02</name>
- <includeTable>includeTable-01</includeTable>
- </catalog>
-</dbimport></programlisting>
- <para>
- Then Cayenne will do reverse engineering for both shop-01 and shop-02 catalogs. First catalog will not be processed for filtering,
- but the second catalog will be processed with “includeTable-01” filter.
- </para>
- <para>
- Let’s assume you have a lot of table prefixes with the same names. Cayenne allows you to mention a pattern as regular expression.
- Using regular expressions is easier way to handle a big amount of database entities than writing filter config for each use-case.
- They make your configuration more readable, understandable and straightforward. There is not complex.
- Let’s see how to use patterns in reverse engineering configuration with complete example.
- </para>
- <programlisting language="xml"><dbimport>
-
- <catalog>shop-01</catalog>
-
- <catalog>
- <name>shop-02</name>
- </catalog>
-
- <catalog>
- <name>shop-03</name>
- <includeTable>includeTable-01</includeTable>
-
- <includeTable>
- <pattern>includeTable-02</pattern>
- </includeTable>
-
- <includeTable>
- <pattern>includeTable-03</pattern>
- <includeColumn>includeColumn-01</includeColumn>
- <excludeColumn>excludeColumn-01</excludeColumn>
- </includeTable>
-
- <excludeTable>excludeTable-01</excludeTable>
-
- <excludeTable>
- <pattern>excludeTable-02</pattern>
- </excludeTable>
-
- <includeColumn>includeColumn-01</includeColumn>
-
- <includeColumn>
- <pattern>includeColumn-02</pattern>
- </includeColumn>
-
- <excludeColumn>excludeColumn-01</excludeColumn>
-
- <excludeColumn>
- <pattern>excludeColumn-02</pattern>
- </excludeColumn>
-
- <includeProcedure>includeProcedure-01</includeProcedure>
-
- <includeProcedure>
- <pattern>includeProcedure-02</pattern>
- </includeProcedure>
-
- <excludeProcedure>excludeProcedure-01</excludeProcedure>
-
- <excludeProcedure>
- <pattern>excludeProcedure-02</pattern>
- </excludeProcedure>
-
- </catalog>
-</dbimport></programlisting>
- <para>The example above should provide you more idea about how to use filtering and patterns
- in Cayenne reverse engineering. You could notice that this example demonstrates you the
- "name" and "pattern" configurations. Yes, you could use these as separates xml element
- and xml attributes. </para>
- <para>
- The cdbimport will execute reverse engineering task for all entities from “shop-01” and “shop-02”, including tables, views, stored procedures
- and table columns. As “shop-03” has variety filter tags, entities from this catalog will be filtered by cdbimport.
- </para>
- </section>
- <section>
- <title>Ant configuration example</title>
- <para> Here is config sample for <code>Ant</code> task:
- <programlisting language="xml"><!-- inside <cdbimport> tag -->
-<catalog>shop-01</catalog>
-
-<catalog name="shop-02"/>
-
-<catalog name="shop-03">
-
- <includeTable>includeTable-01</includeTable>
- <includeTable pattern="includeTable-02"/>
-
- <includeTable pattern="includeTable-03">
- <includeColumn>includeColumn-01</includeColumn>
- <excludeColumn>excludeColumn-01</excludeColumn>
- </includeTable>
-
- <excludeTable>excludeTable-01</excludeTable>
- <excludeTable pattern="excludeTable-02"/>
-
- <includeColumn>includeColumn-01</includeColumn>
- <includeColumn pattern="includeColumn-02"/>
-
- <excludeColumn>excludeColumn-01</excludeColumn>
- <excludeColumn pattern="excludeColumn-02"/>
-
- <includeProcedure>includeProcedure-01</includeProcedure>
- <includeProcedure pattern="includeProcedure-02"/>
-
- <excludeProcedure>excludeProcedure-01</excludeProcedure>
- <excludeProcedure pattern="excludeProcedure-02"/>
-
-</catalog></programlisting>
- </para>
- <note>
- <para>
- In Ant task configuration all filter tags located inside root tag <code><cdbimport></code> as there is no <code><dbimport></code> tag.
- </para>
- </note>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/cayenne-guide/src/docbkx/re-introduction.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/re-introduction.xml b/docs/docbook/cayenne-guide/src/docbkx/re-introduction.xml
deleted file mode 100644
index 37609ac..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/re-introduction.xml
+++ /dev/null
@@ -1,88 +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="re-introduction">
- <title>Introduction</title>
- <section xml:id="what-is-cdbimport">
- <title>"DB-first" Flow</title>
- <para>An ORM system consists of three parts: database, OR mapping and persistent Java classes.
- These parts always need to be kept in sync with each other for the application to work.
- "DB-first" flow is a common and practical approach to synchronization that assumes the
- database to be the master source of the metadata, with other two parts synchronized from
- the DB as the schema evolves. Cayenne provides a number of tools to automate and control
- it. Here is how "DB-first" flow is typically implemented:<itemizedlist>
- <listitem>
- <para> A SQL migrations framework is used to bring a local DB to a certain
- version. This is outside of the scope of Cayenne and is done with a
- third-party tool, such as Liquibase or Flyway.</para>
- </listitem>
- <listitem>
- <para>OR mapping model (Cayenne XML files) are synchronized with the state of the database
- using <code>"cdbimport"</code> tool provdied by Cayenne.</para>
- </listitem>
- <listitem>
- <para>Object layer of the OR mapping model is customized to the developer liking, usually via
- CayenneModeler. Subsequent runs of <code>"cdbimport"</code> will not
- override any customizations that you make.</para>
- </listitem>
- <listitem>
- <para>Java classes are generated using <code>"cgen"</code> tool provided by Cayenne.</para>
- </listitem>
- </itemizedlist></para>
- <para>"cgen" and "cdbimport" tools can be invoked from Maven or Ant as discussed in the
- "Including Cayenne in a Project" chapter or run from CayenneModeler. This chapter will
- mostly focus on "cdbimport". </para>
- <para>
- Here is simple maven configuration to start with:
-
-
- </para>
- </section>
- <section xml:id="re-configuration-file">
- <title>Introduction to "cdbimport"</title>
- <para>Here is a simple Maven configuration of "cdbimport" (for details see <link linkend="mvn-cdbimport">cayenne-maven-plugin</link> documentation)</para>
- <para>
- <programlisting language="xml">
- <plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>cayenne-maven-plugin</artifactId>
- <version><?eval ${project.version}?></version>
-
- <configuration>
- <map>${project.basedir}/src/main/resources/datamap.map.xml</map>
- <dataSource>
- <url><!-- jdbc url --></url>
- <driver><!-- jdbc driver class --></driver>
- <username>username</username>
- <password>password</password>
- </dataSource>
- <dbimport>
- <defaultPackage>com.example.package</defaultPackage>
- <includeTable>.*</includeTable>
- </dbimport>
- </configuration>
- <dependencies>
- <!-- jdbc driver dependency -->
- </dependencies>
- </plugin>
- </programlisting>
- </para>
-
- <para>In the next chapters we will discuss various filtering and other reverse-engineering
- options.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/cayenne-guide/src/docbkx/re-modeler.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/re-modeler.xml b/docs/docbook/cayenne-guide/src/docbkx/re-modeler.xml
deleted file mode 100644
index 1347658..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/re-modeler.xml
+++ /dev/null
@@ -1,122 +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 version="5.0" xml:id="re-modeler" xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:ns="http://docbook.org/ns/docbook">
- <title>Reverse Engineering in Cayenne Modeler</title>
-
- <para>Alternative aproach to using <link linkend="what-is-cdbimport">cdbimport </link> is doing
- reverse engineering from <link linkend="running-cayennemodeler">Cayenne Modeler</link>.
- Currently modeler GUI doesn't support all features of ant/maven tasks but it suffice for
- general DB import. Especially it's a good place to quickly start working on your data model. </para>
-
- <para>
- You can find reverse engineering tool in main modeler menu
- <emphasis role="strong">
- <guimenu>Tools</guimenu> > <guimenuitem>Reengineer Database Schema</guimenuitem>
- </emphasis>
- </para>
-
- <section xml:id="modeler-re-datasource">
- <title>DataSource selection</title>
- <para>First you should select DataSource. If you don't have any DataSource
- yet you can create one from this menu.
- <mediaobject>
- <imageobject condition="web">
- <imagedata fileref="images/re-modeler-datasource-select.png"
- format="PNG" scale="70"/>
- </imageobject>
-
- <textobject>
- <phrase>Datasource selection dialog</phrase>
- </textobject>
-
- <caption>
- <para>Datasource selection dialog.</para>
- </caption>
- </mediaobject>
- </para>
- </section>
-
- <section xml:id="modeler-re-options">
- <title>Reverse engineering options</title>
- <para>Once DataSource is selected you can proceed to reverse engineering
- options.
- <mediaobject>
- <imageobject condition="web">
- <imagedata fileref="images/re-modeler-reverseengineering-dialog.png"
- format="PNG" scale="70"/>
- </imageobject>
-
- <textobject>
- <phrase>Reverse Engineering dialog</phrase>
- </textobject>
-
- <caption>
- <para>Reverse Engineering dialog.</para>
- </caption>
- </mediaobject>
- </para>
-
- <para>
- Here is a list of options to tune what will be processed by reverse engineering:
- <itemizedlist>
- <listitem>
- <para><emphasis role="strong">Select Catalog</emphasis>:
- catalog to process
- <note>
- <para>You can only select one catalog. If you need to import multiple catalogs you need to run process several times.</para>
- </note>
- </para>
- </listitem>
-
- <listitem>
- <para><emphasis role="strong">Table Name Pattern</emphasis>:
- RegExp to filter tables. Default pattern <code>.*</code> includes all tables.
- </para>
- </listitem>
- <listitem>
- <para><emphasis role="strong">Procedure Name Pattern</emphasis>:
- RegExp to filter procedures. Default pattern <code>.*</code> includes all stored procedures.
- </para>
- </listitem>
- <listitem>
- <para><emphasis role="strong">Naming Strategy</emphasis>:
- Currently there is only one naming strategy available.
- See ant/maven tools <link linkend="re-name-generator">documentation</link> for details about naming strategy.
- </para>
- </listitem>
- <listitem>
- <para><emphasis role="strong">Tables with Meaningful PK Pattern</emphasis>:
- Comma separated list of RegExp's for tables that you want to have meaningful primary keys.
- By default no meaningful PKs are created.
- </para>
- </listitem>
- <listitem>
- <para><emphasis role="strong">Use Java primitive types</emphasis>:
- Use primitive types (e.g. <code>int</code>) or Object types (e.g. <code>java.lang.Integer</code>).
- </para>
- </listitem>
- <listitem>
- <para><emphasis role="strong">Use old java.util.Date type</emphasis>:
- Use <code>java.util.Date</code> for all columns with <code>DATE/TIME/TIMESTAMP</code> types.
- By default <code>java.time.*</code> types will be used.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/cayenne-guide/src/docbkx/re-other-settings.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/re-other-settings.xml b/docs/docbook/cayenne-guide/src/docbkx/re-other-settings.xml
deleted file mode 100644
index 29d0c22..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/re-other-settings.xml
+++ /dev/null
@@ -1,65 +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="re-relationships-loading-control">
- <title>Other Settings</title>
- <para>
- In databases relations are defined via foreign keys and there are a lot of different politics according to the level of relationships and
- ways how those relationships could be modeled in database. Anyway, cdbimport is able to recognize basic patterns of relationships, such as
- OneToMany, OneToOne and ManyToMany.
- </para>
- <section xml:id="skip-relationships-loading">
- <title>Skip Relationships Loading</title>
- <para>
- You are able to skip relationships loading by the <code language="xml"><skipRelationshipsLoading></code> element.
- </para>
- <programlisting language="xml">
- <dbimport>
- <skipRelationshipsLoading>true</skipRelationshipsLoading>
- </dbimport></programlisting>
- </section>
- <section xml:id="skip-pk-loading">
- <title>Skip Primary Keys Loading</title>
- <para>
- Another useful Cayenne reverse engineering property is <code language="xml"><skipPrimaryKeyLoading></code>. If you decide to support all relationships at the application layer
- and avoid their management in database, you’ll find useful to turn off primary keys synchronization at all.
- </para>
- <programlisting language="xml">
- <dbimport>
- <skipPrimaryKeyLoading>true</skipPrimaryKeyLoading>
- </dbimport></programlisting>
- </section>
- <section>
- <title>Table Types</title>
- <para>By default, cdbimport imports tables and views. Some databases may support other
- table-like objects, e.g. <code>SYSTEM TABLE, GLOBAL TEMPORARY, LOCAL TEMPORARY, ALIAS,
- SYNONYM</code>, etc. To control which types should be included <code language="xml"
- ><tableType></tableType></code> element is used. Some examples:</para>
- <para> Import tables only (skip views and others and other
- types):<programlisting language="xml">
- <dbimport>
- <tableType>TABLE</tableType>
- </dbimport></programlisting>
- </para>
- <para> Tables and views (<emphasis>the default
- option</emphasis>):<programlisting language="xml">
- <dbimport>
- <tableType>TABLE</tableType>
- <tableType>VIEWS</tableType>
- </dbimport></programlisting></para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/cayenne-guide/src/docbkx/rop-deployment.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/rop-deployment.xml b/docs/docbook/cayenne-guide/src/docbkx/rop-deployment.xml
deleted file mode 100644
index b15a8b9..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/rop-deployment.xml
+++ /dev/null
@@ -1,47 +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="rop-deployment">
- <title>ROP Deployment</title>
- <section xml:id="deploying-rop-server">
- <title>Deploying ROP Server</title>
-
- <note><para>Recent versions of Tomcat and Jetty containers (e.g. Tomcat 6 and 7, Jetty 8) contain code
- addressing a security concern related to "session fixation problem" by resetting the
- existing session ID of any request that requires BASIC authentcaition. If ROP
- service is protected with declarative security (see the ROP tutorial and the
- following chapters on security), this feature prevents the ROP client from attaching
- to its session, resulting in MissingSessionExceptions. To solve that you will need
- to either switch to an alternative security mechanism, or disable "session fixation
- problem" protections of the container. E.g. the later can be achieved in Tomcat 7 by
- adding the following <emphasis>context.xml</emphasis> file to the webapp's META-INF/
- directory:
- <programlisting language="xml"><Context>
- <Valve className="org.apache.catalina.authenticator.BasicAuthenticator"
- changeSessionIdOnAuthentication="false" />
-</Context></programlisting>(The
- <Valve> tag can also be placed within the <Context> in any other locations
- used by Tomcat to load context configurations)</para></note>
-
- </section>
- <section xml:id="deploying-rop-client">
- <title>Deploying ROP Client</title>
- </section>
- <section xml:id="rop-security">
- <title>Security</title>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/cayenne-guide/src/docbkx/rop-introduction.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/rop-introduction.xml b/docs/docbook/cayenne-guide/src/docbkx/rop-introduction.xml
deleted file mode 100644
index fb32ca4..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/rop-introduction.xml
+++ /dev/null
@@ -1,98 +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="introduction-to-rop">
- <title>Introduction to ROP</title>
- <section xml:id="what-is-rop">
- <title>What is ROP</title>
- <para>"Remote Object Persistence" is a low-overhead web services-based technology that
- provides lightweight object persistence and query functionality to 'remote'
- applications. In other words it provides familiar Cayenne API to applications that do
- not have direct access to the database. Instead such applications would access Cayenne
- Web Service (CWS). A single abstract data model (expressed as Cayenne XML DataMap) is
- used on the server and on the client, while execution logic can be partitioned between
- the tiers.The following picture compares a regular Cayenne web application and a rich
- client application that uses remote object persistence technology:</para>
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/remote-object-persistence.jpg" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject></para>
- <para>Persistence stack above consists of the following parts:<itemizedlist>
- <listitem>
- <para>ORM Tier: a server-side Cayenne Java application that directly connects to
- the database via JDBC.</para>
- </listitem>
- <listitem>
- <para>CWS (Cayenne Web Service): A wrapper around an ORM tier that makes it
- accessible to remote CWS clients.</para>
- </listitem>
- <listitem>
- <para>Remote Tier (aka Client Tier): A Java application that has no direct DB
- connection and persists its objects by connecting to remote Cayenne Web
- Service (CWS). Note that CWS Client doesn't have to be a desktop
- application. It can be another server-side application. The word "client"
- means a client of Cayenne Web Service.</para>
- </listitem>
- </itemizedlist></para>
- </section>
- <section xml:id="main-features">
- <title>Main Features</title>
- <itemizedlist>
-
- <listitem>
- <para>Unified approach to lightweight object persistence across multiple
- tiers of a distributed system.</para>
- </listitem>
- <listitem>
- <para>Same abstract object model on the server and on the client.</para>
- </listitem>
- <listitem>
- <para>Client can "bootstrap" from the server by dynamically loading
- persistence metadata.</para>
- </listitem>
- <listitem>
- <para>An ability to define client objects differently than the server ones,
- and still have seamless persistence.</para>
- </listitem>
- <listitem>
- <para>Generic web service interface that doesn't change when object model
- changes.</para>
- </listitem>
- <listitem>
- <para>An ability to work in two modes: dedicated session mode or shared
- ("chat") mode when multiple remote clients collaboratively work on the
- same data.</para>
- </listitem>
- <listitem>
- <para>Lazy object and collection faulting.</para>
- </listitem>
- <listitem>
- <para>Full context lifecycle</para>
- </listitem>
- <listitem>
- <para>Queries, expressions, local query caching, paginated queries.</para>
- </listitem>
- <listitem>
- <para>Validation</para>
- </listitem>
- <listitem>
- <para>Delete Rules</para>
- </listitem>
- </itemizedlist>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/cayenne-guide/src/docbkx/rop-setup.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/rop-setup.xml b/docs/docbook/cayenne-guide/src/docbkx/rop-setup.xml
deleted file mode 100644
index dde1922..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/rop-setup.xml
+++ /dev/null
@@ -1,26 +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="rop-setup">
- <title>ROP Setup</title>
- <section xml:id="rop-system-requirements">
- <title>System Requirements</title>
- </section>
- <section xml:id="rop-jar-files-dependencies">
- <title>Jar Files and Dependencies</title>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/cayenne-guide/src/docbkx/setup.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/setup.xml b/docs/docbook/cayenne-guide/src/docbkx/setup.xml
deleted file mode 100644
index ba804a6..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/setup.xml
+++ /dev/null
@@ -1,176 +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="setup">
- <title>Setup</title>
- <section xml:id="system-requirements">
- <title>System Requirements</title>
- <para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="italic">Java</emphasis>: Cayenne runtime framework and
- CayenneModeler GUI tool are written in 100% Java, and run on any
- Java-compatible platform. Minimal required JDK version depends on the
- version of Cayenne you are using, as shown in the following table:
- <table frame="void">
- <caption>Cayenne Version History</caption>
- <col width="28%"/>
- <col width="36%"/>
- <col width="36%"/>
- <tbody>
- <tr>
- <th>Cayenne Version</th>
- <th>Java Version</th>
- <th>Status</th>
- </tr>
- <tr>
- <td>4.1</td>
- <td>Java 1.8 or newer</td>
- <td>Development</td>
- </tr>
- <tr>
- <td>4.0</td>
- <td>Java 1.7 or newer</td>
- <td>Beta</td>
- </tr>
- <tr>
- <td>3.1</td>
- <td>Java 1.5 or newer</td>
- <td>Stable</td>
- </tr>
- <tr>
- <td>3.0</td>
- <td>Java 1.5</td>
- <td>Aging</td>
- </tr>
- <tr>
- <td>1.2 / 2.0</td>
- <td>Java 1.4</td>
- <td>Legacy</td>
- </tr>
- <tr>
- <td>1.1</td>
- <td>Java 1.3</td>
- <td>Legacy</td>
- </tr>
- </tbody>
- </table></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><emphasis role="italic">JDBC Driver:</emphasis> An appropriate DB-specific
- JDBC driver is needed to access the database. It can be included in the
- application or used in web container DataSource configuration.</para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><emphasis role="italic">Third-party Libraries:</emphasis> Cayenne runtime
- framework has a minimal set of required and a few more optional dependencies
- on third-party open source packages. See
- <link linkend="including-cayenne-in-project">"Including Cayenne in a Project"</link>
- chapter for details.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
- <section xml:id="running-cayennemodeler">
- <title>Running CayenneModeler</title>
- <para>CayenneModeler GUI tool is intended to work with object relational mapping projects. While
- you can edit your XML by hand, it is rarely needed, as the Modeler is a pretty advanced
- tool included in Cayenne distribution. To obtain CayenneModeler, download Cayenne
- distribution archive from
- <link xlink:href="http://cayenne.apache.org/download.html">http://cayenne.apache.org/download.html</link>
- matching the OS you are using. Of course Java needs to be installed on the machine where
- you are going to run the Modeler.
- </para>
- <itemizedlist>
- <listitem>
- <para>OS X distribution contains CayenneModeler.app at the root of the distribution disk
- image.
- </para>
- </listitem>
- <listitem>
- <para>Windows distribution contains CayenneModeler.exe file in the
- <code>bin</code>
- directory.
- </para>
- </listitem>
- <listitem>
- <para>Cross-platform distribution (targeting Linux, but as the name implies, compatible with any
- OS) contains a runnable CayenneModeler.jar in the <code>bin</code> directory. It can be
- executed either by double-clicking, or if the environment is not configured to execute
- jars, by running from command-line:
- </para>
- <screen><prompt>$</prompt> java -jar CayenneModeler.jar</screen>
- </listitem>
- </itemizedlist>
-
- <para>The Modeler can also be started from Maven. While it may look like an exotic way to start a
- GUI application, it has its benefits - no need to download Cayenne distribution, the
- version of the Modeler always matches the version of the framework, the plugin can find
- mapping files in the project automatically. So it is an attractive option to some
- developers. Maven option requires a declaration in the
- POM:
- <programlisting language="xml"><build>
- <plugins>
- <plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>cayenne-modeler-maven-plugin</artifactId>
- <version><?eval ${project.version}?></version>
- </plugin>
- </plugins>
-</build></programlisting>
- </para>
- <para>And then can be run as
- <screen><prompt>$</prompt> mvn cayenne-modeler:run</screen>
- </para>
- <para>
- <table frame="void">
- <caption>modeler plugin parameters</caption>
- <col width="14%"/>
- <col width="7%"/>
- <col width="79%"/>
- <thead>
- <tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>modelFile</code>
- </td>
- <td>File</td>
- <td>Name of the model file to open. Here is some simple example:
- <programlisting language="xml"><plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>cayenne-modeler-maven-plugin</artifactId>
- <version>${cayenne.version}</version>
- <configuration>
- <modelFile>src/main/resources/cayenne.xml</modelFile>
- </configuration>
-</plugin></programlisting>
- </td>
- </tr>
- </tbody>
- </table></para>
- </section>
-</chapter>