http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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 6acc744..0000000 --- a/docs/docbook/cayenne-guide/src/docbkx/queries-sqltemplate.xml +++ /dev/null @@ -1,420 +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> - </section> - <section> - <title>#chain and #chunk</title> - - <para><code>#chain</code> and <code>#chunk</code> directives are used for - conditional inclusion of SQL code. They are used together with - <code>#chain</code> wrapping multiple <code>#chunks</code>. A chunk - evaluates its parameter expression and if it is NULL suppresses rendering of the - enclosed SQL block. A chain renders its prefix and its chunks joined by the - operator. If all the chunks are suppressed, the chain itself is suppressed. This - allows to work with otherwise hard to script SQL semantics. E.g. a WHERE clause - can contain multiple conditions joined with AND or OR. Application code would - like to exclude a condition if its right-hand parameter is not present (similar - to Expression pruning discussed above). If all conditions are excluded, the - entire WHERE clause should be excluded. chain/chunk allows to do that.</para> - <para> - <emphasis role="italic" - >Semantics</emphasis>:<programlisting language="java">#chain(operator) ... #end - #chain(operator prefix) ... #end - #chunk() ... #end - #chunk(param) ... #end </programlisting></para> - <para><emphasis role="italic">Full - example:</emphasis><programlisting language="java">#chain('OR' 'WHERE') - #chunk($name) NAME LIKE #bind($name) #end - #chunk($id) ARTIST_ID > #bind($id) #end - #end" </programlisting></para> - - </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/cde78f0b/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/cde78f0b/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/cde78f0b/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/cde78f0b/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/cde78f0b/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/cde78f0b/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/cde78f0b/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/cde78f0b/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/cde78f0b/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>
