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:22 UTC
[08/14] cayenne git commit: Switch documentation from Docbook to
Asciidoctor format
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/asciidoc/upgrade-guide/src/docs/asciidoc/upgrade-guide.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/upgrade-guide/src/docs/asciidoc/upgrade-guide.adoc b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/upgrade-guide.adoc
new file mode 100644
index 0000000..8d5c21f
--- /dev/null
+++ b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/upgrade-guide.adoc
@@ -0,0 +1,42 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to you under the Apache License, Version
+// 2.0 (the "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0 Unless required by
+// applicable law or agreed to in writing, software distributed under the
+// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+// CONDITIONS OF ANY KIND, either express or implied. See the License for
+// the specific language governing permissions and limitations under the
+// License.
+= Guide to 4.1 Features
+:revnumber: {project-major-version} ({project-version})
+// enable section numbering, limiting depth to 2
+:sectnums:
+:sectnumlevels: 2
+// use custom header
+:cayenne-header: _upgrade-guide/header.html
+:cayenne-header-position: body
+// base path to java code include
+:cayenne-root: {basedir}/../../..
+
+[small]#Copyright © 2011-2017 Apache Software Foundation and individual authors#
+
+.License
+[small]#_Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.
+See the NOTICE file distributed with this work for additional information regarding copyright ownership.
+The ASF licenses this file to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain
+a copy of the License at http://www.apache.org/licenses/LICENSE-2.0_#
+
+[small]#_Unless required by applicable law or agreed to in writing, software distributed under the License
+is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and limitations under the License._#
+
+
+This guide highlights the new features and changes introduced in Apache Cayenne 4.1. For a full list of changes consult
+RELEASE-NOTES.txt included in Cayenne download. For release-specific upgrade instructions check UPGRADE.txt.
+
+include::_upgrade-guide/new-features.adoc[]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/doc/pom.xml
----------------------------------------------------------------------
diff --git a/docs/doc/pom.xml b/docs/doc/pom.xml
index 69d4af3..02574f2 100644
--- a/docs/doc/pom.xml
+++ b/docs/doc/pom.xml
@@ -157,6 +157,7 @@
<!-- this is relative to target/site/apidocs -->
<destDir>doc/api</destDir>
<stylesheet>java</stylesheet>
+ <header><![CDATA[<a href="http://cayenne.apache.org" target="top">Apache Cayenne</a>]]></header>
<additionalDependencies>
<additionalDependency>
<groupId>net.sf.ehcache</groupId>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/cayenne-guide/pom.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/pom.xml b/docs/docbook/cayenne-guide/pom.xml
deleted file mode 100644
index 786f1ef..0000000
--- a/docs/docbook/cayenne-guide/pom.xml
+++ /dev/null
@@ -1,31 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
--->
-
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
- <parent>
- <groupId>org.apache.cayenne.docs</groupId>
- <artifactId>cayenne-docbook</artifactId>
- <version>4.1.M2-SNAPSHOT</version>
- </parent>
-
- <modelVersion>4.0.0</modelVersion>
- <artifactId>cayenne-guide</artifactId>
- <name>cayenne-guide: Docbook - Cayenne Guide</name>
-</project>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/cayenne-guide/src/docbkx/appendix-a.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/appendix-a.xml b/docs/docbook/cayenne-guide/src/docbkx/appendix-a.xml
deleted file mode 100644
index f75ba15..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/appendix-a.xml
+++ /dev/null
@@ -1,190 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="configuration-properties">
- <title>Configuration Properties</title>
- <para>Note that the property names below are defined as constants in
- <code>org.apache.cayenne.configuration.Constants</code> interface. </para>
- <para>
- <table frame="void">
- <caption>Configuration Properties Recognized by ServerRuntime and/or ClientRuntime</caption>
- <col width="67%"/>
- <col width="15%"/>
- <col width="18%"/>
- <thead>
- <tr>
- <th>Property</th>
- <th>Possible Values</th>
- <th>Default Value</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>cayenne.jdbc.driver[.domain_name.node_name]</code> - defines a JDBC driver class to
- use when creating a DataSource. If domain name and optionally - node name
- are specified, the setting overrides DataSource info just for this
- domain/node. Otherwise the override is applied to all domains/nodes in the
- system.</td>
- <td/>
- <td>none, project DataNode configuration is used</td>
- </tr>
- <tr>
- <td><code>cayenne.jdbc.url[.domain_name.node_name] </code>- defines a DB URL to use when
- creating a DataSource. If domain name and optionally - node name are
- specified, the setting overrides DataSource info just for this domain/node.
- Otherwise the override is applied to all domains/nodes in the system.</td>
- <td/>
- <td>none, project DataNode configuration is used</td>
- </tr>
- <tr>
- <td><code>cayenne.jdbc.username[.domain_name.node_name] </code>- defines a DB user name to use
- when creating a DataSource. If domain name and optionally - node name are
- specified, the setting overrides DataSource info just for this domain/node.
- Otherwise the override is applied to all domains/nodes in the system.</td>
- <td/>
- <td>none, project DataNode configuration is used</td>
- </tr>
- <tr>
- <td><code>cayenne.jdbc.password[.domain_name.node_name]</code> - defines a DB password to use
- when creating a DataSource. If domain name and optionally - node name are
- specified, the setting overrides DataSource info just for this domain/node.
- Otherwise the override is applied to all domains/nodes in the system</td>
- <td/>
- <td>none, project DataNode configuration is used</td>
- </tr>
- <tr>
- <td><code>cayenne.jdbc.min_connections[.domain_name.node_name]</code> - defines the DB
- connection pool minimal size. If domain name and optionally - node name are
- specified, the setting overrides DataSource info just for this domain/node.
- Otherwise the override is applied to all domains/nodes in the system</td>
- <td/>
- <td>none, project DataNode configuration is used</td>
- </tr>
- <tr>
- <td><code>cayenne.jdbc.max_connections[.domain_name.node_name]</code> - defines the DB
- connection pool maximum size. If domain name and optionally - node name are
- specified, the setting overrides DataSource info just for this domain/node.
- Otherwise the override is applied to all domains/nodes in the system</td>
- <td/>
- <td>none, project DataNode configuration is used</td>
- </tr>
- <tr>
- <td><code>cayenne.querycache.size</code> - An integer defining the maximum number of entries in
- the query cache. Note that not all QueryCache providers may respect this
- property. MapQueryCache uses it, but the rest would use alternative
- configuration methods.</td>
- <td>any positive int value</td>
- <td>2000</td>
- </tr>
- <tr>
- <td><code>cayenne.server.contexts_sync_strategy</code> - defines whether peer ObjectContexts
- should receive snapshot events after commits from other contexts. If true
- (default), the contexts would automatically synchronize their state with
- peers.</td>
- <td>true, false</td>
- <td>true</td>
- </tr>
- <tr>
- <td><code>cayenne.server.object_retain_strategy</code> - defines fetched objects retain
- strategy for ObjectContexts. When weak or soft strategy is used, objects
- retained by ObjectContext that have no local changes can potetially get
- garbage collected when JVM feels like doing it.</td>
- <td>weak, soft, hard</td>
- <td>weak</td>
- </tr>
- <tr>
- <td><code>cayenne.server.max_id_qualifier_size</code> - defines a maximum number of ID
- qualifiers in the WHERE clause of queries that are generated for paginated
- queries and for DISJOINT_BY_ID prefetch processing. This is needed to avoid
- hitting WHERE clause size limitations and memory usage efficiency.</td>
- <td>any positive int</td>
- <td>10000</td>
- </tr>
- <tr>
- <td><code>cayenne.server.external_tx</code> - defines whether runtime should use
- external transactions.</td>
- <td>true, false</td>
- <td>false</td>
- </tr>
- <tr>
- <td><code>cayenne.rop.service_url</code> - defines the URL of the ROP server</td>
- <td/>
- <td/>
- </tr>
- <tr>
- <td><code>cayenne.rop.service_username</code> - defines the user name for an ROP client to
- login to an ROP server.</td>
- <td/>
- <td/>
- </tr>
- <tr>
- <td><code>cayenne.rop.service_password</code> - defines the password for an ROP client to login
- to an ROP server.</td>
- <td/>
- <td/>
- </tr>
- <tr>
- <td><code>cayenne.rop.shared_session_name</code>- defines the name of the shared session that
- an ROP client wants to join on an ROP server. If omitted, a dedicated
- session is created.</td>
- <td/>
- <td/>
- </tr>
- <tr>
- <td><code>cayenne.rop.service.timeout</code> - a value in milliseconds for the
- ROP client-server connection read operation timeout</td>
- <td>any positive long value</td>
- <td/>
- </tr>
- <tr>
- <td><code>cayenne.rop.channel_events</code> - defines whether client-side DataChannel should
- dispatch events to child ObjectContexts. If set to true, ObjectContexts will
- receive commit events and merge changes committed by peer contexts that
- passed through the common client DataChannel.</td>
- <td>true, false</td>
- <td>false</td>
- </tr>
- <tr>
- <td><code>cayenne.rop.context_change_events</code>- defines whether object property changes in
- the client context result in firing events. Client UI components can listen
- to these events and update the UI. Disabled by default.</td>
- <td>true, false</td>
- <td>false</td>
- </tr>
- <tr>
- <td><code>cayenne.rop.context_lifecycle_events</code> - defines whether object commit and
- rollback operations in the client context result in firing events. Client UI
- components can listen to these events and update the UI. Disabled by
- default.</td>
- <td>true,false</td>
- <td>false</td>
- </tr>
- <tr>
- <td><code>cayenne.server.rop_event_bridge_factory</code> - defines the name of
- the org.apache.cayenne.event.EventBridgeFactory that is passed from the ROP
- server to the client. I.e. server DI would provide a name of the factory,
- passing this name to the client via the wire. The client would instantiate
- it to receive events from the server. Note that this property is stored in
- "cayenne.server.rop_event_bridge_properties" map, not in the main
- "cayenne.properties".</td>
- <td/>
- <td/>
- </tr>
- </tbody>
- </table>
- </para>
-</appendix>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/cayenne-guide/src/docbkx/appendix-b.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/appendix-b.xml b/docs/docbook/cayenne-guide/src/docbkx/appendix-b.xml
deleted file mode 100644
index cf0f035..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/appendix-b.xml
+++ /dev/null
@@ -1,100 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="service-collections">
- <title>Service Collections</title>
- <para>Note that the collection keys below are
- defined as constants in <code>org.apache.cayenne.configuration.Constants</code>
- interface.</para>
- <para>
- <table frame="void">
- <caption>Service Collection Keys Present in ServerRuntime and/or ClientRuntime</caption>
- <col width="42%"/>
- <col width="25%"/>
- <col width="33%"/>
- <thead>
- <tr>
- <th>Collection Property</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>cayenne.properties</code></td>
- <td><code>Map<String,String></code></td>
- <td>Properties used by built-in
- Cayenne services. The keys in this map are the property names from the table
- in Appendix A. Separate copies of this map exist on the server and ROP
- client.</td>
- </tr>
- <tr>
- <td><code>cayenne.server.adapter_detectors</code></td>
- <td><code>List<DbAdapterDetector></code></td>
- <td>Contains
- objects that can discover the type of current database and install the
- correct DbAdapter in runtime.</td>
- </tr>
- <tr>
- <td><code>cayenne.server.domain_filters</code></td>
- <td><code>List<DataChannelFilter></code></td>
- <td>Stores DataDomain filters.</td>
- </tr>
- <tr>
- <td><code>cayenne.server.project_locations</code></td>
- <td><code>List<String></code></td>
- <td>Stores locations of the one of more project configuration files.</td>
- </tr>
- <tr>
- <td><code>cayenne.server.default_types</code></td>
- <td><code>List<ExtendedType></code></td>
- <td>Stores default adapter-agnostic ExtendedTypes. Default ExtendedTypes can be
- overridden / extended by DB-specific DbAdapters as well as by user-provided
- types configured in another colltecion (see
- <code>"cayenne.server.user_types"</code>).</td>
- </tr>
- <tr>
- <td><code>cayenne.server.user_types</code></td>
- <td><code>List<ExtendedType></code></td>
- <td>Stores a
- user-provided ExtendedTypes. This collection will be merged into a full list
- of ExtendedTypes and would override any ExtendedTypes defined in a default
- list, or by a DbAdapter.</td>
- </tr>
- <tr>
- <td><code>cayenne.server.type_factories</code></td>
- <td><code>List<ExtendedTypeFactory></code></td>
- <td>Stores default and user-provided ExtendedTypeFactories. ExtendedTypeFactory
- allows to define ExtendedTypes dynamically for the whole group of Java
- classes. E.g. Cayenne supplies a factory to map all Enums regardless of
- their type.</td>
- </tr>
- <tr>
- <td><code>cayenne.server.rop_event_bridge_properties</code></td>
- <td><code>Map<String, String></code></td>
- <td>Stores event bridge properties passed to the ROP client on
- bootstrap. This means that the map is configured by server DI, and passed to
- the client via the wire. The properties in this map are specific to
- EventBridgeFactory implementation (e.g JMS or XMPP connection prameters).
- One common property is <code>"cayenne.server.rop_event_bridge_factory"</code> that
- defines the type of the factory.</td>
- </tr>
- </tbody>
- </table>
- </para>
-
-</appendix>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/cayenne-guide/src/docbkx/appendix-c.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/appendix-c.xml b/docs/docbook/cayenne-guide/src/docbkx/appendix-c.xml
deleted file mode 100644
index 8b036af..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/appendix-c.xml
+++ /dev/null
@@ -1,147 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="expressions-bnf">
- <title>Expressions BNF</title>
- <para>
- <programlisting>
-TOKENS
-<DEFAULT> SKIP : {
-" "
-| "\t"
-| "\n"
-| "\r"
-}
-
-<DEFAULT> TOKEN : {
-<NULL: "null" | "NULL">
-| <TRUE: "true" | "TRUE">
-| <FALSE: "false" | "FALSE">
-}
-
-<DEFAULT> TOKEN : {
-<PROPERTY_PATH: <IDENTIFIER> ("." <IDENTIFIER>)*>
-}
-
-<DEFAULT> TOKEN : {
-<IDENTIFIER: <LETTER> (<LETTER> | <DIGIT>)* (["+"])?>
-| <#LETTER: ["_","a"-"z","A"-"Z"]>
-| <#DIGIT: ["0"-"9"]>
-}
-
-/**
- * Quoted Strings, whose object value is stored in the token manager's
- * "literalValue" field. Both single and double qoutes are allowed
- */<DEFAULT> MORE : {
-"\'" : WithinSingleQuoteLiteral
-| "\"" : WithinDoubleQuoteLiteral
-}
-
-<WithinSingleQuoteLiteral> MORE : {
-<ESC: "\\" (["n","r","t","b","f","\\","\'","`","\""] | (["0"-"3"])? ["0"-"7"] (["0"-"7"])?)> : {
-| <~["\'","\\"]> : {
-}
-
-<WithinSingleQuoteLiteral> TOKEN : {
-<SINGLE_QUOTED_STRING: "\'"> : DEFAULT
-}
-
-<WithinDoubleQuoteLiteral> MORE : {
-<STRING_ESC: <ESC>> : {
-| <~["\"","\\"]> : {
-}
-
-<WithinDoubleQuoteLiteral> TOKEN : {
-<DOUBLE_QUOTED_STRING: "\""> : DEFAULT
-}
-
-/**
- * Integer or real Numeric literal, whose object value is stored in the token manager's
- * "literalValue" field.
- */<DEFAULT> TOKEN : {
-<INT_LITERAL: ("0" (["0"-"7"])* | ["1"-"9"] (["0"-"9"])* | "0" ["x","X"] (["0"-"9","a"-"f","A"-"F"])+)
- (["l","L","h","H"])?> : {
-| <FLOAT_LITERAL: <DEC_FLT> (<EXPONENT>)? (<FLT_SUFF>)? | <DEC_DIGITS> <EXPONENT> (<FLT_SUFF>)?
-| <DEC_DIGITS> <FLT_SUFF>> : {
-| <#DEC_FLT: (["0"-"9"])+ "." (["0"-"9"])* | "." (["0"-"9"])+>
-| <#DEC_DIGITS: (["0"-"9"])+>
-| <#EXPONENT: ["e","E"] (["+","-"])? (["0"-"9"])+>
-| <#FLT_SUFF: ["d","D","f","F","b","B"]>
-}
-
-NON-TERMINALS
- expression := orCondition <EOF>
- orCondition := andCondition ( "or" andCondition )*
- andCondition := notCondition ( "and" notCondition )*
- notCondition := ( "not" | "!" ) simpleCondition
- | simpleCondition
- simpleCondition := <TRUE>
- | <FALSE>
- | scalarConditionExpression
- ( simpleNotCondition
- | ( "=" | "==" ) scalarExpression
- | ( "!=" | "<>" ) scalarExpression
- | "<=" scalarExpression
- | "<" scalarExpression | ">" scalarExpression
- | ">=" scalarExpression
- | "like" scalarExpression
- | "likeIgnoreCase" scalarExpression
- | "in" ( namedParameter | "(" scalarCommaList ")" )
- | "between" scalarExpression "and" scalarExpression
- )?
- simpleNotCondition := ( "not" | "!" )
- ( "like" scalarExpression
- | "likeIgnoreCase" scalarExpression
- | "in" ( namedParameter | "(" scalarCommaList ")" )
- | "between" scalarExpression "and" scalarExpression
- )
- scalarCommaList := ( scalarConstExpression ( "," scalarConstExpression )* )
- scalarConditionExpression := scalarNumericExpression
- | <SINGLE_QUOTED_STRING>
- | <DOUBLE_QUOTED_STRING>
- | <NULL>
- scalarExpression := scalarConditionExpression
- | <TRUE>
- | <FALSE>
- scalarConstExpression := <SINGLE_QUOTED_STRING>
- | <DOUBLE_QUOTED_STRING>
- | namedParameter
- | <INT_LITERAL>
- | <FLOAT_LITERAL>
- | <TRUE>
- | <FALSE>
- scalarNumericExpression := multiplySubtractExp
- ( "+" multiplySubtractExp | "-" multiplySubtractExp )*
- multiplySubtractExp := numericTerm ( "*" numericTerm | "/" numericTerm )*
- numericTerm := ( "+" )? numericPrimary
- | "-" numericPrimary
- numericPrimary := "(" orCondition ")"
- | pathExpression
- | namedParameter
- | <INT_LITERAL>
- | <FLOAT_LITERAL>
- namedParameter := "$" <PROPERTY_PATH>
- pathExpression := ( <PROPERTY_PATH>
- | "obj:" <PROPERTY_PATH>
- | "db:" <PROPERTY_PATH>
- | "enum:" <PROPERTY_PATH> )
-
-</programlisting>
- </para>
-
-
-</appendix>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml b/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml
deleted file mode 100644
index 6d76ef2..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml
+++ /dev/null
@@ -1,95 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="cayenne-mapping-structure">
- <title>Cayenne Mapping Structure</title>
- <section xml:id="cayenne-project">
- <title>Cayenne Project</title>
- <para>A Cayenne project is an XML representation of a model connecting database schema with
- Java classes. A project is normally created and manipulated via CayenneModeler GUI and
- then used to initialize Cayenne runtime. A project is made of one or more files. There's
- always a root project descriptor file in any valid project. It is normally called
- <code>cayenne-xyz.xml</code>, where "xyz" is the name of the project.</para>
- <para>Project descriptor can reference DataMap files, one per DataMap. DataMap files are
- normally called <code>xyz.map.xml</code>, where "xyz" is the name of the DataMap. For
- legacy reasons this naming convention is different from the convention for the root
- project descriptor above, and we may align it in the future versions. Here is how a
- typical project might look on the file
- system:<screen><prompt>$</prompt> <userinput>ls -l</userinput>
-total 24
--rw-r--r-- 1 cayenne staff 491 Jan 28 18:25 cayenne-project.xml
--rw-r--r-- 1 cayenne staff 313 Jan 28 18:25 datamap.map.xml</screen></para>
- <para>DataMap are referenced by name in the root
- descriptor:<programlisting language="xml"><map name="datamap"/></programlisting></para>
- <para>Map files are resolved by Cayenne by appending "<code>.map.xml</code>" extension to the
- map name, and resolving the resulting string relative to the root descriptor URI. The
- following sections discuss varios ORM model objects, without regards to their XML
- representation. XML format details are really unimportant to the Cayenne users.</para>
- </section>
- <section xml:id="datamap">
- <title>DataMap</title>
- <para>DataMap is a container of persistent entities and other object-relational metadata.
- DataMap provides developers with a scope to organize their entities, but it does not
- provide a namespace for entities. In fact all DataMaps present in runtime are combined
- in a single namespace. Each DataMap must be associated with a DataNode. This is how
- Cayenne knows which database to use when running a query.</para>
- </section>
- <section xml:id="datanode">
- <title>DataNode</title>
- <para>DataNode is model of a database. It is actually pretty simple. It has an arbitrary
- user-provided name and information needed to create or locate a JDBC DataSource. Most
- projects only have one DataNode, though there may be any number of nodes if
- needed.</para>
- </section>
- <section xml:id="dbentity">
- <title>DbEntity</title>
- <para>DbEntity is a model of a single DB table or view. DbEntity is made of DbAttributes
- that correspond to columns, and DbRelationships that map PK/FK pairs. DbRelationships
- are not strictly tied to FK constraints in DB, and should be mapped for all logical
- "relationships" between the tables.</para>
- </section>
- <section xml:id="objentity">
- <title>ObjEntity</title>
- <para>ObjEntity is a model of a single persistent Java class. ObjEntity is made of
- ObjAttributes and ObjRelationships. Both correspond to entity class properties. However
- ObjAttributes represent "simple" properties (normally things like String, numbers,
- dates, etc.), while ObjRelationships correspond to properties that have a type of
- another entity. </para>
- <para>ObjEntity maps to one or more DbEntities. There's always one "root" DbEntity for each
- ObjEntity. ObjAttribiute maps to a DbAttribute or an Embeddable. Most often mapped
- DbAttribute is from the root DbEntity. Sometimes mapping is done to a DbAttribute from
- another DbEntity somehow related to the root DbEntity. Such ObjAttribute is called
- "flattened". Similarly ObjRelationship maps either to a single DbRelationship, or to a
- chain of DbRelationships ("flattened" ObjRelationship).</para>
- <para>ObjEntities may also contain mapping of their lifecycle callback methods.</para>
- </section>
- <section xml:id="embeddable">
- <title>Embeddable</title>
- <para>Embeddable is a model of a Java class that acts as a single attribute of an ObjEntity,
- but maps to multiple columns in the database.</para>
- </section>
- <section xml:id="procedure">
- <title>Procedure</title>
- <para>A model of a stored procedure in the database.</para>
- </section>
- <section xml:id="query">
- <title>Query</title>
- <para>A model of a query. Cayenne allows queries to be mapped in Cayenne project, or created
- in the code. Depending on the circumstances the users may take one or the other
- approach.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml b/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml
deleted file mode 100644
index 4c6b9ae..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml
+++ /dev/null
@@ -1,116 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="cayennemodeler-application">
- <title>CayenneModeler Application</title>
- <section xml:id="working-with-mapping-projects">
- <title>Working with Mapping Projects</title>
- <para></para>
- </section>
- <section xml:id="reverse-engineering-database">
- <title>Reverse Engineering Database</title>
- <para>
- See chapter <link linkend="re-modeler">Reverse Engineering in Cayenne Modeler</link>
- </para>
- </section>
- <section xml:id="generating-database-schema">
- <title>Generating Database Schema</title>
- <para>
- With Cayenne Modeler you can create simple database schemas without any additional database tools.
- This is a good option for initial database setup if you completely created you model with the Modeler.
- You can start SQL schema generation by selecting menu
- <emphasis role="strong">
- <guimenu>Tools</guimenu> > <guimenuitem>Generate Database Schema</guimenuitem>
- </emphasis>
- </para>
- <para>
- You can select what database parts should be generated and what tables you want
- </para>
- </section>
- <section xml:id="migrations">
- <title>Migrations</title>
- <para> </para>
- </section>
- <section xml:id="generating-java-classes">
- <title>Generating Java Classes</title>
- <para>
- Before using Cayenne in you code you need to generate java source code for persistent objects.
- This can be done with Modeler GUI or via <link linkend="mvn-cgen">cgen</link> maven/ant plugin.
- </para>
- <para>
- To generate classes in the modeler use
- <emphasis role="strong">
- <guimenu>Tools</guimenu> > <guimenuitem>Generate Classes</guimenuitem>
- </emphasis>
- </para>
- <para>
- There is three default types of code generation
- <itemizedlist>
- <listitem>
- <para><emphasis role="strong">Standard Persistent Objects</emphasis></para>
- <para>
- Default type of generation suitable for almost all cases.
- Use this type unless you now what exactly you need to customize.
- </para>
- </listitem>
- <listitem>
- <para><emphasis role="strong">Client Persistent Objects</emphasis></para>
- <para>
-
- </para>
- </listitem>
- <listitem>
- <para><emphasis role="strong">Advanced.</emphasis></para>
- <para>
- In advanced mode you can control almost all aspects of code generation including custom templates for java code.
- See default Cayenne templates on
- <link xlink:href="https://github.com/apache/cayenne/tree/master/cayenne-tools/src/main/resources/templates/v1_2">GitHub</link>
- as an example
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
- <section xml:id="modeling-inheritance">
- <title>Modeling Inheritance</title>
- <para> </para>
- </section>
- <section xml:id="modeling-generic-persistence-classes">
- <title>Modeling Generic Persistent Classes</title>
- <para>Normally each ObjEntity is mapped to a specific Java class (such as Artist or
- Painting) that explicitly declare all entity properties as pairs of getters and setters.
- However Cayenne allows to map a completly generic class to any number of entities. The
- only expectation is that a generic class implements
- <emphasis>org.apache.cayenne.DataObject</emphasis>. So an ideal candidate for a
- generic class is CayenneDataObject, or some custom subclass of CayenneDataObject.</para>
- <para>If you don't enter anything for Java Class of an ObjEntity, Cayenne assumes generic
- mapping and uses the following implicit rules to determine a class of a generic object.
- If DataMap "Custom Superclass" is set, runtime uses this class to instantiate new
- objects. If not, org.apache.cayenne.CayenneDataObject is used.</para>
- <para>Class generation procedures (either done in the Modeler or with Ant or Maven) would
- skip entities that are mapped to CayenneDataObject explicitly or have no class
- mapping.</para>
- </section>
- <section xml:id="mapping-objattributes-to-custom-classes">
- <title>Mapping ObjAttributes to Custom Classes</title>
- <para> </para>
- </section>
- <section xml:id="modeling-pk-generation-strategy">
- <title>Modeling Primary Key Generation Strategy</title>
- <para> </para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/cayenne-guide/src/docbkx/current-limitations.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/current-limitations.xml b/docs/docbook/cayenne-guide/src/docbkx/current-limitations.xml
deleted file mode 100644
index 4b69324..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/current-limitations.xml
+++ /dev/null
@@ -1,20 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="current-limitations">
- <title>Current Limitations</title>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml b/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml
deleted file mode 100644
index 89b6e38..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml
+++ /dev/null
@@ -1,470 +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="customizing-cayenne-runtime">
- <title>Customizing Cayenne Runtime</title>
- <section xml:id="depdendency-injection-container">
- <title>Dependency Injection Container</title>
- <para>Cayenne runtime is built around a small powerful dependency injection (DI) container. Just
- like other popular DI technologies, such as Spring or Guice, Cayenne DI container
- manages sets of interdependent objects and allows users to configure them. These
- objects are regular Java objects. We are calling them "services" in this document to
- distinguish from all other objects that are not configured in the container and are not
- managed. DI container is responsible for service instantiation, injecting correct
- dependencies, maintaining service instances scope, and dispatching scope events to
- services. </para>
- <para>The services are configured in special Java classes called "modules". Each module
- defines binding of service interfaces to implementation instances, implementation types
- or providers of implementation instances. There are no XML configuration files, and all
- the bindings are type-safe. The container supports injection into instance variables and
- constructor parameters based on the <code>@Inject</code> annotation. This mechanism is
- very close to Google Guice.</para>
- <para>The discussion later in this chapter demonstrates a standalone DI container. But keep in
- mind that Cayenne already has a built-in Injector, and a set of default modules. A
- Cayenne user would normally only use the API below to write custom extension modules
- that will be loaded in that existing container when creating ServerRuntime. See
- "Starting and Stopping ServerRuntime" chapter for an example of passing an extension
- module to Cayenne.</para>
- <para>Cayenne DI probably has ~80% of the features expected in a DI container and has no
- dependency on the rest of Cayenne, so in theory can be used as an application-wide DI
- engine. But it's primary purpose is still to serve Cayenne. Hence there are no plans to
- expand it beyond Cayenne needs. It is an ideal "embedded" DI that does not interfere
- with Spring, Guice or any other such framework present elsewhere in the
- application.</para>
- <section xml:id="di-bindings-api">
- <title>DI Bindings API</title>
- <para>To have a working DI container, we need three things: service interfaces and
- classes, a module that describes service bindings, a container that loads the
- module, and resolves the depedencies. Let's start with service interfaces and
- classes:<programlisting language="java">public interface Service1 {
- public String getString();
-}</programlisting><programlisting language="java">public interface Service2 {
- public int getInt();
-}</programlisting></para>
- <para>A service implementation using instance variable
- injection:<programlisting language="java">public class Service1Impl implements Service1 {
- @Inject
- private Service2 service2;
-
- public String getString() {
- return service2.getInt() + "_Service1Impl";
- }
-}</programlisting>Same
- thing, but using constructor
- injection:<programlisting language="java">public class Service1Impl implements Service1 {
-
- private Service2 service2;
-
- public Service1Impl(@Inject Service2 service2) {
- this.service2 = service2;
- }
-
- public String getString() {
- return service2.getInt() + "_Service1Impl";
- }
-}
-</programlisting><programlisting language="java">public class Service2Impl implements Service2 {
- private int i;
-
- public int getInt() {
- return i++;
- }
-}</programlisting></para>
- <para>Now let's create a module implementing
- <code>org.apache.cayenne.tutorial.di.Module</code> interface that will contain
- DI configuration. A module binds service objects to keys that are reference. Binder
- provided by container implements fluent API to connect the key to implementation,
- and to configure various binding options (the options, such as scope, are
- demonstrated later in this chapter). The simplest form of a key is a Java Class
- object representing service interface. Here is a module that binds Service1 and
- Service2 to corresponding default implementations:</para>
- <para>
- <programlisting language="java">public class Module1 implements Module {
-
- public void configure(Binder binder) {
- binder.bind(Service1.class).to(Service1Impl.class);
- binder.bind(Service2.class).to(Service2Impl.class);
- }
-}</programlisting>
- </para>
- <para>Once we have at least one module, we can create a DI container.
- <code>org.apache.cayenne.di.Injector</code> is the container class in
- Cayenne:<programlisting language="java">Injector injector = DIBootstrap.createInjector(new Module1());</programlisting></para>
- <para>Now that we have created the container, we can obtain services from it and call
- their
- methods:<programlisting language="java">Service1 s1 = injector.getInstance(Service1.class);
-for (int i = 0; i < 5; i++) {
- System.out.println("S1 String: " + s1.getString());
-}</programlisting></para>
- <para>This outputs the following lines, demonstrating that s1 was Service1Impl and
- Service2 injected into it was
- Service2Impl:<programlisting language="java">0_Service1Impl
-1_Service1Impl
-2_Service1Impl
-3_Service1Impl
-4_Service1Impl</programlisting></para>
- <para>There are more flavors of bindings:
- <programlisting language="java">// binding to instance - allowing user to create and configure instance
-// inside the module class
-binder.bind(Service2.class).toInstance(new Service2Impl());
-
-// binding to provider - delegating instance creation to a special
-// provider class
-binder.bind(Service1.class).toProvider(Service1Provider.class);
-
-// binding to provider instance
-binder.bind(Service1.class).toProviderInstance(new Service1Provider());
-
-// multiple bindings of the same type using Key
-// injection can reference the key name in annotation:
-// @Inject("i1")
-// private Service2 service2;
-binder.bind(Key.get(Service2.class, "i1")).to(Service2Impl.class);
-binder.bind(Key.get(Service2.class, "i2")).to(Service2Impl.class);</programlisting></para>
- <para>Another types of confiuguration that can be bound in the container are lists and
- maps. They will be discussed in the following chapters. </para>
- </section>
- <section xml:id="managing-services-lifecycle">
- <title>Service Lifecycle</title>
- <para>An important feature of the Cayenne DI container is instance <emphasis role="italic"
- >scope</emphasis>. The default scope (implicitly used in all examples above) is
- "singleton", meaning that a binding would result in creation of only one service
- instance, that will be repeatedly returned from
- <code>Injector.getInstance(..)</code>, as well as injected into classes that
- declare it as a dependency. </para>
- <para>Singleton scope dispatches a "BeforeScopeEnd" event to interested services. This
- event occurs before the scope is shutdown, i.e. when
- <code>Injector.shutdown()</code> is called. Note that the built-in Cayenne
- injector is shutdown behind the scenes when <code>ServerRuntime.shutdown()</code>
- is invoked. Services may register as listeners for this event by annotating a
- no-argument method with <code>@BeforeScopeEnd</code> annotation. Such method should
- be implemented if a service needs to clean up some resources, stop threads,
- etc.</para>
- <para>Another useful scope is "no scope", meaning that every time a container is asked to provide
- a service instance for a given key, a new instance will be created and
- returned:<programlisting language="java">binder.bind(Service2.class).to(Service2Impl.class).withoutScope();</programlisting>Users
- can also create their own scopes, e.g. a web application request scope or a session
- scope. Most often than not custom scopes can be created as instances of
- <code>org.apache.cayenne.di.spi.DefaultScope</code> with startup and shutdown
- managed by the application (e.g. singleton scope is a DefaultScope managed by the
- Injector) . </para>
- </section>
- <section xml:id="overriding-services">
- <title>Overriding Services</title>
- <para>Cayenne DI allows to override services already definied in the current module, or
- more commonly - some other module in the the same container. Actually there's no
- special API to override a service, you'd just bind the service key again with a new
- implementation or provider. The last binding for a key takes precedence. This means
- that the order of modules is important when configuring a container. The built-in
- Cayenne injector ensures that Cayenne standard modules are loaded first, followed by
- optional user extension modules. This way the application can override the standard
- services in Cayenne.</para>
- </section>
- </section>
- <section xml:id="ways-to-customize-runtime">
- <title> Customization Strategies</title>
- <para>The previous section discussed how Cayenne DI works in general terms. Since Cayenne users
- will mostly be dealing with an existing Injector provided by ServerRuntime, it is
- important to understand how to build custom extensions to a preconfigured container. As
- shown in "Starting and Stopping ServerRuntime" chapter, custom extensions are done by
- writing an aplication DI module (or multiple modules) that configures service overrides.
- This section shows all the configuration possibilities in detail, including changing
- properties of the existing services, contributing services to standard service lists and
- maps, and overriding service implementations. All the code examples later in this
- section are assumed to be placed in an application module "configure" method:</para><programlisting language="java">public class MyExtensionsModule implements Module {
- public void configure(Binder binder) {
- // customizations go here...
- }
-}</programlisting><programlisting language="java">Module extensions = new MyExtensionsModule();
-ServerRuntime runtime = ServerRuntime.builder()
- .addConfig("com/example/cayenne-mydomain.xml")
- .addModule(extensions)
- .build();</programlisting>
- <section xml:id="changing-properties-of-existing-services">
- <title>Changing Properties of Existing Services</title>
- <para>Many built-in Cayenne services change their behavior based on a value of some
- environment property. A user may change Cayenne behavior without even knowing which
- services are responsible for it, but setting a specific value of a known property.
- Supported property names are listed in "Appendix A".</para>
- <para>There are two ways to set service properties. The most obvious one is to pass it
- to the JVM with -D flag on startup.
- E.g.<screen><prompt>$</prompt> java -Dcayenne.server.contexts_sync_strategy=false ...</screen></para>
- <para>A second one is to contribute a property to
- <code>org.apache.cayenne.configuration.DefaultRuntimeProperties.properties
- </code>map (see the next section on how to do that). This map contains the default
- property values and can accept application-specific values, overrding the defaults. </para>
- <para>Note that if a property value is a name of a Java class, when this Java class is
- instantiated by Cayenne, the container performs injection of instance variables. So
- even the dynamically specified Java classes can use @Inject annotation to get a hold
- of other Cayenne services.</para>
- <para>If the same property is specified both in the command line and in the properties
- map, the command-line value takes precedence. The map value will be ignored. This
- way Cayenne runtime can be reconfigured during deployment.</para>
- </section>
- <section xml:id="contributing-to-service-lists-maps">
- <title>Contributing to Service Collections</title>
- <para>Cayenne can be extended by adding custom objects to named maps or lists bound in
- DI. We are calling these lists/maps "service collections". A service collection
- allows things like appending a custom strategy to a list of built-in strategies.
- E.g. an application that needs to install a custom DbAdapter for some database type
- may contribute an instance of custom DbAdapterDetector to a
- <code>org.apache.cayenne.configuration.server.DefaultDbAdapterFactory.detectors</code>
- list:</para>
- <programlisting language="java">public class MyDbAdapterDetector implements DbAdapterDetector {
- public DbAdapter createAdapter(DatabaseMetaData md) throws SQLException {
- // check if we support this database and retun custom adapter
- ...
- }
-}</programlisting>
- <programlisting language="java">// since build-in list for this key is a singleton, repeated
-// calls to 'bindList' will return the same instance
-binder.bindList(DefaultDbAdapterFactory.DETECTORS_LIST)
- .add(MyDbAdapterDetector.class);</programlisting>
- <para>Maps are customized using a similar "<code>bindMap</code>" method.</para>
- <para>The names of built-in collections are listed in "Appendix B".</para>
- </section>
- <section xml:id="alternative-service-implementations">
- <title>Alternative Service Implementations</title>
- <para>As mentioned above, custom modules are loaded by ServerRuntime after the built-in
- modules. So it is easy to redefine a built-in service in Cayenne by rebinding
- desired implementations or providers. To do that, first we need to know what those
- services to redefine are. While we describe some of them in the following sections,
- the best way to get a full list is to check the source code of the Cayenne version
- you are using and namely look in
- <code>org.apache.cayenne.configuration.server.ServerModule</code> - the main
- built-in module in Cayenne. </para>
- <para>Now an example of overriding <code>QueryCache</code> service. The default
- implementation of this service is provided by <code>MapQueryCacheProvider</code>.
- But if we want to use <code>EhCacheQueryCache</code> (a Cayenne wrapper for the
- EhCache framework), we can define it like
- this:<programlisting language="java">binder.bind(QueryCache.class).to(EhCacheQueryCache.class);</programlisting></para>
- </section>
- </section>
- <section>
- <title>Using custom data types</title>
- <section>
- <title>Value object type</title>
- <para>
- <code>ValueObjectType</code> is a new and lightweight alternative to the Extended Types API described in the following section.
- In most cases is should be preferred as is it easier to understand and use. Currently only one case is known when <code>ExtendedType</code> should be used:
- when your value object can be mapped on different JDBC types.
- </para>
- <para>
- In order to use your custom data type you should implement <code>ValueObjectType</code> describing it in terms of some type already known to Cayenne
- (e.g. backed by system or user ExtendedType).
- Let's assume we want to support some data type called <code>Money</code>:
- <programlisting language="java"><![CDATA[public class Money {
- private BigDecimal value;
-
- public Money(BigDecimal value) {
- this.value = value;
- }
-
- public BigDecimal getValue() {
- return value;
- }
-
- // .. some other business logic ..
-}]]></programlisting>
- Here is how <code>ValueObjectType</code> that will allow to store our <code>Money</code> class as <code>BigDecimal</code>
- can be implemented:
- <programlisting language="java"><![CDATA[public class MoneyValueObjectType implements ValueObjectType<Money, BigDecimal> {
-
- @Override
- public Class<BigDecimal> getTargetType() {
- return BigDecimal.class;
- }
-
- @Override
- public Class<Money> getValueType() {
- return Money.class;
- }
-
- @Override
- public Money toJavaObject(BigDecimal value) {
- return new Money(value);
- }
-
- @Override
- public BigDecimal fromJavaObject(Money object) {
- return object.getValue();
- }
-
- @Override
- public String toCacheKey(Money object) {
- return object.getValue().toString();
- }
-}]]></programlisting>
- </para>
- <para>
- Last step is to register this new type in <code>ServerRuntime</code>:
- <programlisting language="java"><![CDATA[ServerRuntime runtime = ServerRuntime.builder()
- .addConfig("cayenne-project.xml")
- .addModule(binder -> ServerModule.contributeValueObjectTypes(binder).add(MoneyValueObjectType.class))
- .build();]]></programlisting>
- </para>
- <para>More examples of implementation you can find in
- <link xlink:href="https://github.com/apache/cayenne/tree/master/cayenne-joda">cayenne-joda module</link>.</para>
- </section>
- <section xml:id="extendedtypes">
- <title>Extended Types</title>
- <para>JDBC specification defines a set of "standard" database column types (defined in java.sql.Types class)
- and a very specific mapping of these types to Java Object Types, such as java.lang.String,
- java.math.BigDecimal, etc. Sometimes there is a need to use a custom Java type not known to JDBC driver and
- Cayenne allows to configure it. For this Cayenne needs to know how to instantiate this type from
- a database "primitive" value, and conversely, how to transform an object of the custom type to
- a JDBC-compatible object.</para>
- <section xml:id="supporting-non-standard-types">
- <title>Supporting Non-Standard Types</title>
- <para>For supporting non-standard type you should define it via an interface <code>org.apache.cayenne.access.types.ExtendedType</code>.
- An implementation must provide <code>ExtendedType.getClassName()</code> method that returns
- a fully qualified Java class name for the supported custom type, and a number of methods
- that convert data between JDBC and custom type.
- The following example demonstrates how to add a custom DoubleArrayType
- to store <code>java.lang.Double[]</code> as a custom string in a database:</para>
- <programlisting language="java">
-/**
-* Defines methods to read Java objects from JDBC ResultSets and write as parameters of
-* PreparedStatements.
-*/
-public class DoubleArrayType implements ExtendedType {
-
- private final String SEPARATOR = ",";
-
- /**
- * Returns a full name of Java class that this ExtendedType supports.
- */
- @Override
- public String getClassName() {
- return Double[].class.getCanonicalName();
- }
-
- /**
- * Initializes a single parameter of a PreparedStatement with object value.
- */
- @Override
- public void setJdbcObject(PreparedStatement statement, Object value,
- int pos, int type, int scale) throws Exception {
-
- String str = StringUtils.join((Double[]) value, SEPARATOR);
- statement.setString(pos, str);
- }
-
-
- /**
- * Reads an object from JDBC ResultSet column, converting it to class returned by
- * 'getClassName' method.
- *
- * @throws Exception if read error occurred, or an object can't be converted to a
- * target Java class.
- */
- @Override
- public Object materializeObject(ResultSet rs, int index, int type) throws Exception {
- String[] str = rs.getString(index).split(SEPARATOR);
- Double[] res = new Double[str.length];
-
- for (int i = 0; i < str.length; i++) {
- res[i] = Double.valueOf(str[i]);
- }
-
- return res;
- }
-
- /**
- * Reads an object from a stored procedure OUT parameter, converting it to class
- * returned by 'getClassName' method.
- *
- * @throws Exception if read error ocurred, or an object can't be converted to a
- * target Java class.
- */
- @Override
- public Object materializeObject(CallableStatement rs, int index, int type) throws Exception {
- String[] str = rs.getString(index).split(SEPARATOR);
- Double[] res = new Double[str.length];
-
- for (int i = 0; i < str.length; i++) {
- res[i] = Double.valueOf(str[i]);
- }
-
- return res;
- }
-}
- </programlisting>
- <para>For Java7</para>
- <programlisting language="java">
-// add DoubleArrayType to list of user types
-ServerRuntime runtime = ServerRuntime.builder()
- .addConfig("cayenne-project.xml")
- .addModule(new Module() {
- @Override
- public void configure(Binder binder) {
- ServerModule.contributeUserTypes(binder).add(new DoubleArrayType());
- }
- })
- .build();
- </programlisting>
- <para>For Java8</para>
- <programlisting language="java">
-// add DoubleArrayType to list of user types
-ServerRuntime runtime = ServerRuntime.builder()
- .addConfig("cayenne-project.xml")
- .addModule(binder -> ServerModule.contributeUserTypes(binder).add(new DoubleArrayType()))
- .build();
- </programlisting>
- </section>
- <section xml:id="dbadapters-and-extended-types">
- <title>DbAdapters and Extended Types</title>
- <para>As shown in the example above, ExtendedTypes are stored by DbAdapter. In fact DbAdapters often install
- their own extended types to address incompatibilities, incompleteness and differences between
- JDBC drivers in handling "standard" JDBC types. For instance some drivers support reading large
- character columns (CLOB) as java.sql.Clob, but some other - as "character stream", etc.
- Adapters provided with Cayenne override <code>configureExtendedTypes()</code> method to install their own types,
- possibly substituting Cayenne defaults. Custom DbAdapters can use the same technique.</para>
- </section>
- </section>
- </section>
- <section xml:id="noteworthy-runtime-components">
- <title>Noteworthy Built-in Services</title>
- <section xml:id="jdbceventlogger">
- <title>JdbcEventLogger</title>
- <para><code>org.apache.cayenne.log.JdbcEventLogger</code> is the service that defines
- logging API for Cayenne internals. It provides facilities for logging queries,
- commits, transactions, etc. The default implementation is
- <code>org.apache.cayenne.log.Slf4jJdbcEventLogger</code> that performs logging
- via slf4j-api library. Cayenne library includes another potentially useful
- logger - <code>org.apache.cayenne.log.FormattedSlf4jJdbcEventLogger</code> that
- produces formatted multiline SQL output that can be easier to read.</para>
- </section>
- <section xml:id="datasourcefactory">
- <title>DataSourceFactory</title>
- <para>Factory that returns <code>javax.sql.DataSource</code> object based on the configuration provided in the
- "nodeDescriptor".
- </para>
- </section>
- <section xml:id="datachannelfilter">
- <title>DataChannelFilter</title>
- <para> An interface of a filter that allows to intercept DataChannel operations. Filters allow
- to implement chains of custom processors around a DataChannel, that can be used for
- security, monitoring, business logic, providing context to lifecycle event listeners,
- etc.
- </para>
- </section>
- <section xml:id="querycache">
- <title>QueryCache</title>
- <para>Defines API of a cache that stores query results.</para>
- </section>
- </section>
-</chapter>