You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by nt...@apache.org on 2018/01/05 14:21:34 UTC
[06/11] cayenne git commit: CAY-2371 Switch documentation from
Docbook to Asciidoctor format
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/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 6f3fb6c..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:<programlisting>~: ls -l
-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</programlisting></para>
- <para>DataMap are referenced by name in the root
- descriptor:<programlisting><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/7783cd34/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 4e41174..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml
+++ /dev/null
@@ -1,60 +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>
- </section>
- <section xml:id="reverse-engineering-database">
- <title>Reverse Engineering Database</title>
- </section>
- <section xml:id="generating-database-schema">
- <title>Generating Database Schema</title>
- </section>
- <section xml:id="migrations">
- <title>Migrations</title>
- </section>
- <section xml:id="generating-java-classes">
- <title>Generating Java Classes</title>
- </section>
- <section xml:id="modeling-inheritance">
- <title>Modeling Inheritance</title>
- </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>
- </section>
- <section xml:id="modeling-pk-generation-strategy">
- <title>Modeling Primary Key Generation Strategy</title>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/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/7783cd34/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 d8155ee..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml
+++ /dev/null
@@ -1,279 +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>public class MyExtensionsModule implements Module {
- public void configure(Binder binder) {
- // customizations go here...
- }
-}</programlisting><programlisting language="java">Module extensions = new MyExtensionsModule();
-ServerRuntime runtime =
- new ServerRuntime("com/example/cayenne-mydomain.xml", extensions);</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.<programlisting>java -Dcayenne.server.contexts_sync_strategy=false ...</programlisting></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 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.CommonsJdbcEventLogger</code> that performs logging
- via commons-logging library. Cayenne library includes another potentially useful
- logger - <code>org.apache.cayenne.log.FormattedCommonsJdbcEventLogger</code> that
- produces formatted multiline SQL output that can be easier to read.</para>
- </section>
- <section xml:id="datasourcefactory">
- <title>DataSourceFactory</title>
- </section>
- <section xml:id="datachannelfilter">
- <title>DataChannelFilter</title>
- </section>
- <section xml:id="querycache">
- <title>QueryCache</title>
- </section>
- <section xml:id="extendedtypes">
- <title>ExtendedTypes</title>
- </section>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/docs/docbook/cayenne-guide/src/docbkx/expressions.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/expressions.xml b/docs/docbook/cayenne-guide/src/docbkx/expressions.xml
deleted file mode 100644
index 34257f3..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/expressions.xml
+++ /dev/null
@@ -1,265 +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="expressions">
- <title>Expressions</title>
- <section xml:id="expressions-overview">
- <title>Expressions Overview</title>
- <para>Cayenne provides a simple yet powerful object-based expression language. The most common
- usese of expressions are to build qualifiers and orderings of queries that are later
- converted to SQL by Cayenne and to evaluate in-memory against specific objects (to
- access certain values in the object graph or to perform in-memory object filtering and
- sorting). Cayenne provides API to build expressions in the code and a parser to create
- expressions from strings.</para>
- </section>
- <section xml:id="path-expressions">
- <title>Path Expressions</title>
- <para>Before discussing how to build expressions, it is important to understand one group of
- expressions widely used in Cayenne - path expressions. There are two types of path
- expressions - object and database, used for navigating graphs of connected objects or
- joined DB tables respectively. Object paths are much more commonly used, as after all
- Cayenne is supposed to provide a degree of isolation of the object model from the
- database. However database paths are helpful in certain situations. General structure of
- path expressions is the following:<programlisting> [db:]segment[+][.segment[+]...]</programlisting><itemizedlist>
- <listitem>
- <para>"db:" is an optional prefix indicating that the following path is a DB
- path. Otherwise it is an object path.</para>
- </listitem>
- <listitem>
- <para>"segment" is a name of a property (relationship or attribute in Cayenne
- terms) in the path. Path must have at least one segment; segments are
- separated by dot (".").</para>
- </listitem>
- <listitem>
- <para>"+" An "OUTER JOIN" path component. Currently "+" only has effect when
- translated to SQL as OUTER JOIN. When evaluating expressions in memory, it
- is ignored.</para>
- </listitem>
- </itemizedlist></para>
- <para>An object path expression represents a chain of property names rooted in a certain
- (unspecified during expression creation) object and "navigating" to its related value.
- E.g. a path expression "artist.name" might be a property path starting from a Painting
- object, pointing to the related Artist object, and then to its name attribute. A few
- more examples:</para>
- <para>
- <itemizedlist>
- <listitem>
- <para>"name" - can be used to navigate (read) the "name" property of a Person
- (or any other type of object that has a "name" property).</para>
- </listitem>
- <listitem>
- <para>"artist.exhibits.closingDate" - can be used to navigate to a closing date
- of any of the exhibits of a Painting's Artist object.</para>
- </listitem>
- <listitem>
- <para>"artist.exhibits+.closingDate" - same as the previous example, but when
- translated into SQL, an OUTER JOIN will be used for "exhibits".</para>
- </listitem>
- </itemizedlist>
- </para>
- <para>Similarly a database path expression is a dot-separated path through DB table joins
- and columns. In Cayenne joins are mapped as DbRelationships with some symbolic names
- (the closest concept to DbRelationship name in the DB world is a named foreign key
- constraint. But DbRelationship names are usually chosen arbitrarily, without regard to
- constraints naming or even constraints presence). A database path therefore might look
- like this - "db:dbrelationshipX.dbrelationshipY.COLUMN_Z". More specific examples:<itemizedlist>
- <listitem>
- <para>"db:NAME" - can be used to navigate to the value of "NAME" column of some
- unspecified table.</para>
- </listitem>
- <listitem>
- <para>"db:artist.artistExhibits.exhibit.CLOSING_DATE" - can be used to match a
- closing date of any of the exhibits of a related artist record.</para>
- </listitem>
- </itemizedlist></para>
- <para>Cayenne supports "aliases" in path Expressions. E.g. the same expression can be
- written using explicit path or an alias:<itemizedlist>
- <listitem>
- <para>"artist.exhibits.closingDate" - full path</para>
- </listitem>
- <listitem>
- <para>"e.closingDate" - alias "e" is used for "artist.exhibits".</para>
- </listitem>
- </itemizedlist>SelectQuery using the second form of the path expression must be made
- aware of the alias via <emphasis role="italic">
- "SelectQuery.aliasPathSplits(..)"</emphasis>, otherwise an Exception will be
- thrown. The main use of aliases is to allow users to control how SQL joins are generated
- if the same path is encountered more than once in any given Expression. Each alias for
- any given path would result in a separate join. Without aliases, a single join will be
- used for a group of matching paths.</para>
- </section>
- <section xml:id="expressions-from-strings">
- <title>Creating Expressions from Strings </title>
- <para>While in most cases users are likely to rely on API from the following section for
- expression creation, we'll start by showing String expressions, as this will help
- understanding the semantics. A Cayenne expression can be represented as a String, which
- can be later converted to an expression object using <code>Expression.fromString</code>
- static method. Here is an
- example:<programlisting>String expString = "name like 'A%' and price < 1000";
-Expression exp = Expression.fromString(expString);</programlisting>This
- particular expression may be used to match Paintings with names that start with "A" and
- a price less than $1000. While this example is pretty self-explanatory, there are a few
- points worth mentioning. "name" and "price" here are object paths discussed earlier. As
- always, paths themselves are not attached to a specific root entity and can be applied
- to any entity that has similarly named attributes or relationships. So when we are
- saying that this expression "may be used to match Paintings", we are implying that there
- may be other entities, for which this expression is valid. Now the expression details... </para>
- <para><emphasis role="italic">Character constants</emphasis> that are not paths or numeric values
- should be enclosed in single or double quotes. Two of the expressions below are
- equivalent:<programlisting>name = 'ABC'
-
-// double quotes are escaped inside Java Strings of course
-name = \"ABC\"</programlisting></para>
- <para><emphasis role="italic">Case sensitivity.</emphasis> Expression operators are all case
- sensitive and are usually lowercase. Complex words follow the java camel-case
- style:<programlisting>// valid
-name likeIgnoreCase 'A%'
-
-// invalid - will throw a parse exception
-name LIKEIGNORECASE 'A%'</programlisting></para>
- <para><emphasis role="italic">Grouping with parenthesis:</emphasis>
- <programlisting>value = (price + 250.00) * 3</programlisting>
- </para>
- <para><emphasis role="italic">Path prefixes.</emphasis> Object expressions are unquoted strings,
- optionally prefixed by "obj:" (usually they are not prefixed at all actually). Database
- expressions are always prefixed with "db:". A special kind of prefix, not discussed yet
- is "enum:" that prefixes an enumeration
- constant:<programlisting>// object path
-name = 'Salvador Dali'
-
-// same object path - a rarely used form
-obj:name = 'Salvador Dali'
-
-// multi-segment object path
-artist.name = 'Salvador Dali'
-
-// db path
-db:NAME = 'Salvador Dali'
-
-// enumeration constant
-name = enum:org.foo.EnumClass.VALUE1</programlisting></para>
- <para>
- <emphasis role="italic">Binary conditions</emphasis> are expressions that contain a path
- on the left, a value on the right, and some operation between them, such as equals,
- like, etc. They can be used as qualifiers in
- SelectQueries:<programlisting>name like 'A%'</programlisting>
- <emphasis role="italic">Named parameters.</emphasis> Expressions can have named parameters (names that
- start with "$"). Parameterized expressions allow to create reusable expression
- templates. Also if an Expression contains a complex object that doesn't have a simple
- String representation (e.g. a Date, a DataObject, an ObjectId), parameterizing such
- expression is the only way to represent it as String. Here are some
- examples:<programlisting>Expression template = Expression.fromString("name = $name");
-...
-Map p1 = Collections.singletonMap("name", "Salvador Dali");
-Expression qualifier1 = template.expWithParameters(p1);
-...
-Map p2 = Collections.singletonMap("name", "Monet");
-Expression qualifier2 = template.expWithParameters(p2);</programlisting>To
- create a named parameterized expression with a LIKE clause, SQL wildcards must be part
- of the values in the Map and not the expression string
- itself:<programlisting>Expression template = Expression.fromString("name like $name");
-...
-Map p1 = Collections.singletonMap("name", "Salvador%");
-Expression qualifier1 = template.expWithParameters(p1);</programlisting>When
- matching on a relationship, parameters can be Persistent objects or
- ObjectIds:<programlisting>Expression template = Expression.fromString("artist = $artist");
-...
-Artist dali = // asume we fetched this one already
-Map p1 = Collections.singletonMap("artist", dali);
-Expression qualifier1 = template.expWithParameters(p1);</programlisting>Uninitialized
- parameters will be automatically pruned from expressions, so a user can omit some
- parameters when creating an expression from a parameterized
- template:<programlisting>Expression template = Expression.fromString("name like $name and dateOfBirth > $date");
-...
-Map p1 = Collections.singletonMap("name", "Salvador%");
-Expression qualifier1 = template.expWithParameters(p1);
-
-// qualifier1 is now equals to "name like 'Salvador%'", the 'dateOfBirth' condition was
-// pruned, as no value was specified for the $date parameter</programlisting></para>
- <para><emphasis role="italic">Null handling.</emphasis> Handling of Java nulls as operands
- is no different from normal values. Instead of using special conditional operators, like
- SQL does (IS NULL, IS NOT NULL), "=" and "!=" expressions can be used directly with null
- values. It is up to Cayenne to translate expressions with nulls to the valid SQL.</para>
- <para>
- <note>
- <para>A formal definition of all possible valid expressions in a form of JavaCC
- grammar is provided in Appendix C</para>
- </note>
- </para>
- </section>
- <section xml:id="expressions-with-expressionfactory">
- <title>Creating Expressions with API</title>
- <para>Creating expressions from Strings is a powerful and dynamic approach, however a safer
- alternative is to use Java API. It provides some degree of compile-time checking of
- expressions validity. The API is cenetred around ExpressionFactory class, and the
- Expression class. ExpressionFactory contains a number of rather self-explanatory factory
- methods. We won't be going over all of them in detail, but will rather show a few
- general examples and some gotchas. </para>
- <para>The following code recreates the expression from the previous chapter, but now using
- expression
- API:<programlisting>// String expression: name like 'A%' and price < 1000
-Expression e1 = ExpressionFactory.likeExp(Painting.NAME_PROPERTY, "A%");
-Expression e2 = ExpressionFactory.lessExp(Painting.PRICE_PROPERTY, 1000);
-Expression finalExp = e1.andExp(e2); </programlisting>This
- is more verbose than creating it from String, but it is also more resilient to the
- entity properties renaming and precludes semantic errors in the expression String.<note>
- <para>The last line in the example above shows how to create a new expression by
- "chaining" 2 other epxressions. A common error when chaining expressions is to
- assume that "andExp" and "orExp" append another expression to the current
- expression. In fact a new expression is created. I.e. Expression API treats
- existing expressions as immutable.</para>
- </note></para>
- <para>As discussed earlier, Cayenne supports aliases in path Expressions, allowing to
- control how SQL joins are generated if the same path is encountered more than once in
- the same Expression. Two ExpressionFactory methods allow to implicitly generate aliases
- to "split" match paths into individual joins if
- needed:<programlisting>Expression matchAllExp(String path, Collection values)
-Expression matchAllExp(String path, Object... values)</programlisting></para>
- <para>"Path" argument to both of these methods can use a split character (a pipe symbol '|')
- instead of dot to indicate that relationship following a path should be split into a
- separate set of joins, one per collection value. There can only be one split at most in
- any given path. Split must always precede a relationship. E.g. "|exhibits.paintings",
- "exhibits|paintings", etc. Internally Cayenne would generate distinct aliases for each
- of the split expressions, forcing separate joins.</para>
- </section>
- <section xml:id="expressions-in-memory">
- <title>Evaluating Expressions in Memory</title>
- <para>When used in a query, an expression is converted to SQL WHERE clause (or ORDER BY
- clause) by Cayenne during query execution. Thus the actual evaluation against the data
- is done by the database engine. However the same expressions can also be used for
- accessing object properties, calculating values, in-memory filtering. </para>
- <para>Checking whether an object satisfies an
- expression:<programlisting>Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob");
-User user = ...
-if(e.match(user)) {
- ...
-}</programlisting>Reading
- property
- value:<programlisting>Expression e = Expression.fromString(User.NAME_PROPERTY);
-String name = e.evaluate(user);</programlisting></para>
- <para>Filtering a list of
- objects:<programlisting>Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob");
-List<User> unfiltered = ...
-List<User> filtered = e.filterObjects(unfiltered);</programlisting></para>
- <para>
- <note>
- <para>Current limitation of in-memory expressions is that no collections are
- permitted in the property path.</para>
- </note>
- </para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-client.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-client.xml b/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-client.xml
deleted file mode 100644
index a95a0fd..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-client.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="implementing-rop-client">
- <title>Implementing ROP Client</title>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.xml b/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.xml
deleted file mode 100644
index 3032fd1..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.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="implementing-rop-server">
- <title>Implementing ROP Server</title>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml b/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml
deleted file mode 100644
index 359bef9..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml
+++ /dev/null
@@ -1,546 +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="including-cayenne-in-project">
- <title>Including Cayenne in a Project</title>
- <section xml:id="jar-files-and-depdendencies">
- <title>Jar Files and Dependencies</title>
- <para>Cayenne distribution contains the following core runtime jars in the distribution
- <code>lib</code> directory: <itemizedlist>
- <listitem>
- <para><emphasis role="italic">cayenne-server-x.x.jar</emphasis> - contains full
- Cayenne runtime (DI, adapters, DB access classes, etc.). Most applications
- will use only this file.</para>
- </listitem>
- <listitem>
- <para>cayenne-client-x.x.jar - a subset of cayenne-server.jar trimmed for use on
- the client in an ROP application.</para>
- </listitem>
- <listitem>
- <para>Other cayenne-* jars - various Cayenne extensions.</para>
- </listitem>
- </itemizedlist></para>
- <para>When using <code>cayenne-server-x.x.jar</code> you'll need a few third party jars (all
- included in <code>lib/third-party</code> directory of the distribution): <itemizedlist>
- <listitem>
- <para><link xlink:href="http://velocity.apache.org/">Apache Velocity
- Template Engine</link>, version 1.6.x (and all its dependencies bundled
- with velocity-dep)</para>
- </listitem>
- <listitem>
- <para><link xlink:href="http://commons.apache.org/collections/">Apache Commons
- Collections</link>, version 3.2.1</para>
- </listitem>
- <listitem>
- <para><link xlink:href="http://commons.apache.org/logging/">Apache
- Commons Logging</link>, version 1.1</para>
- </listitem>
- </itemizedlist></para>
- <para>Cayenne integrates with various caching, clustering and other frameworks. These
- optional integrations will require other third-party jars that the users will need to
- obtain on their own.</para>
- </section>
- <section xml:id="maven-projects">
- <title>Maven Projects</title>
- <para>If you are using Maven, you won't have to deal with figuring out the dependencies. You
- can simply include cayenne-server artifact in your
- POM:<programlisting><dependency>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-server</artifactId>
- <version>X.Y.Z</version>
-</dependency></programlisting></para>
- <para>Additionally Cayenne provides a Maven plugin with a set of goals to perform various project
- tasks, such as synching generated Java classes with the mapping, described in the
- following subsection. The full plugin name is
- <code>org.apache.cayenne.plugins:maven-cayenne-plugin</code>.</para>
- <section xml:id="mvn-cgen">
- <title>cgen</title>
- <para><code>cgen</code> is a <code>maven-cayenne-plugin</code> goal that generates and maintains
- source (.java) files of persistent objects based on a DataMap. By default, it is
- bound to the generate-sources phase. If "makePairs" is set to "true" (which is the
- recommended default), this task will generate a pair of classes
- (superclass/subclass) for each ObjEntity in the DataMap. Superclasses should not be
- changed manually, since they are always overwritten. Subclasses are never
- overwritten and may be later customized by the user. If "makePairs" is set to
- "false", a single class will be generated for each ObjEntity. </para>
- <para>By creating custom templates, you can use cgen to generate other output (such as
- web pages, reports, specialized code templates) based on DataMap information.</para>
- <para>
- <table frame="void">
- <caption>cgen required parameters</caption>
- <col width="14%"/>
- <col width="6%"/>
- <col width="80%"/>
- <thead>
- <tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>map</code>
- </td>
- <td>File</td>
- <td>DataMap XML file which serves as a source of metadata for class
- generation. E.g.
- <code>${project.basedir}/src/main/resources/my.map.xml</code></td>
- </tr>
- <tr>
- <td><code>destDir</code></td>
- <td>File</td>
- <td>Root destination directory for Java classes (ignoring their package
- names).</td>
- </tr>
- </tbody>
- </table>
- <table frame="void">
- <caption>cgen optional parameters</caption>
- <col width="33%"/>
- <col width="8%"/>
- <col width="59%"/>
- <thead>
- <tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>additionalMaps</code>
- </td>
- <td>File</td>
- <td>A directory that contains additional DataMap XML files that may be
- needed to resolve cross-DataMap relationships for the the main
- DataMap, for which class generation occurs.</td>
- </tr>
- <tr>
- <td><code>client</code></td>
- <td>boolean</td>
- <td>Whether we are generating classes for the client tier in a Remote
- Object Persistence application. "False" by default.</td>
- </tr>
- <tr>
- <td><code>embeddableTemplate</code></td>
- <td>String</td>
- <td>Location of a custom Velocity template file for Embeddable class
- generation. If omitted, default template is used.</td>
- </tr>
- <tr>
- <td><code>embeddableSuperTemplate</code></td>
- <td>String</td>
- <td>Location of a custom Velocity template file for Embeddable
- superclass generation. Ignored unless "makepairs" set to "true". If
- omitted, default template is used.</td>
- </tr>
- <tr>
- <td><code>encoding</code></td>
- <td>String</td>
- <td>Generated files encoding if different from the default on current
- platform. Target encoding must be supported by the JVM running the
- build. Standard encodings supported by Java on all platforms are
- US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16. See
- javadocs for java.nio.charset.Charset for more information.</td>
- </tr>
- <tr>
- <td><code>excludeEntities</code></td>
- <td>String</td>
- <td>A comma-separated list of ObjEntity patterns (expressed as a perl5
- regex) to exclude from template generation. By default none of the
- DataMap entities are excluded.</td>
- </tr>
- <tr>
- <td><code>includeEntities</code></td>
- <td>String</td>
- <td>A comma-separated list of ObjEntity patterns (expressed as a perl5
- regex) to include from template generation. By default all DataMap
- entities are included.</td>
- </tr>
- <tr>
- <td><code>makePairs</code></td>
- <td>boolean</td>
- <td>If "true" (a recommended default), will generate subclass/superclass
- pairs, with all generated code placed in superclass.</td>
- </tr>
- <tr>
- <td><code>mode</code></td>
- <td>String</td>
- <td>Specifies class generator iteration target. There are three possible
- values: "entity" (default), "datamap", "all". "entity" performs one
- generator iteration for each included ObjEntity, applying either
- standard to custom entity templates. "datamap" performs a single
- iteration, applying DataMap templates. "All" is a combination of
- entity and datamap.</td>
- </tr>
- <tr>
- <td><code>overwrite</code></td>
- <td>boolean</td>
- <td>Only has effect when "makePairs" is set to "false". If "overwrite"
- os "true", will overwrite older versions of generated classes.</td>
- </tr>
- <tr>
- <td><code>superPkg</code></td>
- <td>String</td>
- <td>Java package name of generated superclasses. Only has effect if
- "makepairs" and "usePkgPath" are set to "true" (both are true by
- default). Defines a common package for all generated Java classes.
- If omitted, each superclass will be placed in the same package as
- subclass.</td>
- </tr>
- <tr>
- <td><code>superTemplate</code></td>
- <td>String</td>
- <td>Location of a custom Velocity template file for ObjEntity superclass
- generation. Only has effect if "makepairs" set to "true". If
- omitted, default template is used.</td>
- </tr>
- <tr>
- <td><code>template</code></td>
- <td>String</td>
- <td>Location of a custom Velocity template file for ObjEntity class
- generation. If omitted, default template is used.</td>
- </tr>
- <tr>
- <td><code>usePkgPath</code></td>
- <td>boolean</td>
- <td>If set to "true" (default), a directory tree will be generated in
- "destDir" corresponding to the class package structure, if set to
- "false", classes will be generated in "destDir" ignoring their
- package.</td>
- </tr>
- </tbody>
- </table>
- Example - a typical class generation scenario, where pairs of classes are
- generated, and superclasses are placed in a separate package:
- <programlisting><plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>maven-cayenne-plugin</artifactId>
- <version>X.Y.Z</version>
-
- <!--
- There's an intermittent problem when using Maven/cgen in Eclipse with m2eclipse plugin that
- requires placing "configuration" section at the plugin level, instead of execution
- level.
- -->
- <configuration>
- <map>${project.basedir}/src/main/resources/my.map.xml</map>
- <destDir>${project.basedir}/src/main/java</destDir>
- <superPkg>org.example.model.auto</superPkg>
- </configuration>
-
- <executions>
- <execution>
- <goals>
- <goal>cgen</goal>
- </goals>
- </execution>
- </executions>
-</plugin></programlisting></para>
- </section>
- <section xml:id="mvn-cdbgen">
- <title>cdbgen</title>
- <para><code>cdbgen</code> is a <code>maven-cayenne-plugin</code> goal that drops and/or generates
- tables in a database on Cayenne DataMap. By default, it is bound to the
- pre-integration-test phase.<table frame="void">
- <caption>cdbgen required parameters</caption>
- <col width="14%"/>
- <col width="10%"/>
- <col width="76%"/>
- <thead>
- <tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>map</code>
- </td>
- <td>File</td>
- <td>DataMap XML file which serves as a source of metadata for DB schema
- generation. E.g.
- <code>${project.basedir}/src/main/resources/my.map.xml</code></td>
- </tr>
- <tr>
- <td><code>driver</code></td>
- <td>String</td>
- <td>A class of JDBC driver to use for the target database.</td>
- </tr>
- <tr>
- <td><code>url</code></td>
- <td>String</td>
- <td>JDBC connection URL of a target database.</td>
- </tr>
- </tbody>
- </table></para>
- <para>
- <table frame="void">
- <caption>cdbgen optional parameters</caption>
- <col width="18%"/>
- <col width="11%"/>
- <col width="75%"/>
- <thead>
- <tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>adapter</code>
- </td>
- <td>String</td>
- <td>Java class name implementing org.apache.cayenne.dba.DbAdapter. While
- this attribute is optional (a generic JdbcAdapter is used if not
- set), it is highly recommended to specify correct target
- adapter.</td>
- </tr>
- <tr>
- <td><code>createFK</code></td>
- <td>boolean</td>
- <td>Indicates whether cdbgen should create foreign key constraints. Default is "true".</td>
- </tr>
- <tr>
- <td><code>createPK</code></td>
- <td>boolean</td>
- <td>Indicates whether cdbgen should create Cayenne-specific auto PK objects. Default is
- "true".</td>
- </tr>
- <tr>
- <td><code>createTables</code></td>
- <td>boolean</td>
- <td>Indicates whether cdbgen should create new tables. Default is "true".</td>
- </tr>
- <tr>
- <td><code>dropPK</code></td>
- <td>boolean</td>
- <td>Indicates whether cdbgen should drop Cayenne primary key support objects. Default is
- "false".</td>
- </tr>
- <tr>
- <td><code>dropTables</code></td>
- <td>boolean</td>
- <td>Indicates whether cdbgen should drop the tables before attempting to create new ones.
- Default is "false".</td>
- </tr>
- <tr>
- <td><code>password</code></td>
- <td>String</td>
- <td>Database user password.</td>
- </tr>
- <tr>
- <td><code>username</code></td>
- <td>String</td>
- <td>Database user name.</td>
- </tr>
- </tbody>
- </table>
- </para>
- <para>Example - creating a DB schema on a local HSQLDB
- database:<programlisting><plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>maven-cayenne-plugin</artifactId>
- <version>X.Y.Z</version>
-
- <executions>
- <execution>
- <configuration>
- <map>${project.basedir}/src/main/resources/my.map.xml</map>
- <url>jdbc:hsqldb:hsql://localhost/testdb</url>
- <adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter</adapter>
- <driver>org.hsqldb.jdbcDriver</driver>
- <username>sa</username>
- </configuration>
- <goals>
- <goal>cdbgen</goal>
- </goals>
- </execution>
- </executions>
-</plugin></programlisting></para>
- </section>
- <section xml:id="mvn-cdbimport">
- <title>cdbimport</title>
- <para><code>cdbimport</code> is a <code>maven-cayenne-plugin</code> goal that generates
- a DataMap based on an existing database schema. By default, it is bound to the
- generate-sources phase. This allows you to generate your DataMap prior to building
- your project, which may be necessary if you are also using the cgen task.<table
- frame="void">
- <caption>cdbimport required parameters</caption>
- <col width="14%"/>
- <col width="10%"/>
- <col width="76%"/>
- <thead>
- <tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>map</code>
- </td>
- <td>File</td>
- <td>DataMap XML file which is the destination of the schema import.
- Maybe an existing file. If this file does not exist, it is created
- when cdbimport is executed. E.g.
- <code>${project.basedir}/src/main/resources/my.map.xml</code></td>
- </tr>
- <tr>
- <td><code>driver</code></td>
- <td>String</td>
- <td>A class of JDBC driver to use for the target database.</td>
- </tr>
- <tr>
- <td><code>url</code></td>
- <td>String</td>
- <td>JDBC connection URL of a target database.</td>
- </tr>
- </tbody>
- </table></para>
- <para>
- <table frame="void">
- <caption>cdbimport optional parameters</caption>
- <col width="25%"/>
- <col width="10%"/>
- <col width="65%"/>
- <thead>
- <tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>adapter</code>
- </td>
- <td>String</td>
- <td>Java class name implementing org.apache.cayenne.dba.DbAdapter. While
- this attribute is optional (a generic JdbcAdapter is used if not
- set), it is highly recommended to specify correct target
- adapter.</td>
- </tr>
- <tr>
- <td><code>importProcedures</code></td>
- <td>boolean</td>
- <td>Indicates whether stored procedures should be imported from the
- database. Default is false. </td>
- </tr>
- <tr>
- <td><code>meaningfulPk</code></td>
- <td>boolean</td>
- <td>Indicates whether primary keys should be mapped as attributes of the
- ObjEntity. Default is false. </td>
- </tr>
- <tr>
- <td><code>namingStrategy</code></td>
- <td>String</td>
- <td>The naming strategy used for mapping database names to object entity
- names. Default is
- <code>org.apache.cayenne.map.naming.SmartNamingStrategy</code>.
- </td>
- </tr>
- <tr>
- <td><code>overwriteExisting</code></td>
- <td>boolean</td>
- <td>Indicates whether existing DB and object entities should be
- overwritten. This is an all-or-nothing setting. If you need finer
- granularity, use the CayenneModeler. Default is "true". </td>
- </tr>
- <tr>
- <td><code>password</code></td>
- <td>String</td>
- <td>Database user password.</td>
- </tr>
- <tr>
- <td><code>procedurePattern</code></td>
- <td>String</td>
- <td>Pattern to match stored procedure names against for import. Default
- is to match all stored procedures. This value is only meaningful if
- importProcedures is true. </td>
- </tr>
- <tr>
- <td><code>schemaName</code></td>
- <td>String</td>
- <td>Database schema to import tables/stored procedures from. </td>
- </tr>
- <tr>
- <td><code>tablePattern</code></td>
- <td>String</td>
- <td>Pattern to match table names against for import. Default is to match
- all tables. </td>
- </tr>
- <tr>
- <td><code>username</code></td>
- <td>String</td>
- <td>Database user name.</td>
- </tr>
- </tbody>
- </table>
- </para>
- <para>Example - loading a DB schema from a local HSQLDB database (essentially a reverse operation
- compared to the cdbgen example above)
- :<programlisting><plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>maven-cayenne-plugin</artifactId>
- <version>X.Y.Z</version>
-
- <executions>
- <execution>
- <configuration>
- <map>${project.basedir}/src/main/resources/my.map.xml</map>
- <url>jdbc:mysql://127.0.0.1/mydb</url>
- <adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter</adapter>
- <driver>com.mysql.jdbc.Driver</driver>
- <username>sa</username>
- </configuration>
- <goals>
- <goal>cdbimport</goal>
- </goals>
- </execution>
- </executions>
-</plugin></programlisting></para>
- </section>
- </section>
- <section xml:id="ant-projects">
- <title>Ant Projects</title>
- <section xml:id="ant-cgen">
- <title>cgen</title>
- </section>
- <section xml:id="ant-cdbgen">
- <title>cdbgen</title>
- </section>
- <section xml:id="ant-cdbimport">
- <title>cdbimport</title>
- <para>This is an Ant counterpart of "cdbimport" goal of maven-cayenne-plugin described
- above. It has exactly the same properties. Here is a usage
- example:<programlisting> <cdbimport map="${context.dir}/WEB-INF/my.map.xml"
- driver="com.mysql.jdbc.Driver"
- url="jdbc:mysql://127.0.0.1/mydb"
- username="sa"/> </programlisting>
- </para>
- </section>
- <section xml:id="ant-cdataport">
- <title>cdataport</title>
- </section>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/docs/docbook/cayenne-guide/src/docbkx/index.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/index.xml b/docs/docbook/cayenne-guide/src/docbkx/index.xml
deleted file mode 100644
index 0e850e8..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/index.xml
+++ /dev/null
@@ -1,46 +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.
--->
-<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="cayenne-guide" xmlns:xi="http://www.w3.org/2001/XInclude">
- <info>
- <title>Cayenne Guide</title>
- <copyright>
- <year>2011-2017</year>
- <holder>Apache Software Foundation and individual authors</holder>
- </copyright>
- <legalnotice>
- <title>License</title>
- <para>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</para>
-
- <para>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.</para>
- </legalnotice>
- </info>
- <xi:include href="part1.xml"/>
- <xi:include href="part2.xml"/>
- <xi:include href="part3.xml"/>
- <xi:include href="appendix-a.xml"/>
- <xi:include href="appendix-b.xml"/>
- <xi:include href="appendix-c.xml"/>
-</book>