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>
