http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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 3383e01..0000000 --- a/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml +++ /dev/null @@ -1,473 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to you under the Apache License, Version - 2.0 (the "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 Unless required by - applicable law or agreed to in writing, software distributed under the - License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR - CONDITIONS OF ANY KIND, either express or implied. See the License for - the specific language governing permissions and limitations under the - License. ---> -<chapter xmlns="http://docbook.org/ns/docbook"; xmlns:xlink="http://www.w3.org/1999/xlink"; version="5.0" xml:id="customizing-cayenne-runtime"> - <title>Customizing Cayenne Runtime</title> - <section xml:id="depdendency-injection-container"> - <title>Dependency Injection Container</title> - <para>Cayenne runtime is built around a small powerful dependency injection (DI) container. Just - like other popular DI technologies, such as Spring or Guice, Cayenne DI container - manages sets of interdependent objects and allows users to configure them. These - objects are regular Java objects. We are calling them "services" in this document to - distinguish from all other objects that are not configured in the container and are not - managed. DI container is responsible for service instantiation, injecting correct - dependencies, maintaining service instances scope, and dispatching scope events to - services. </para> - <para>The services are configured in special Java classes called "modules". Each module - defines binding of service interfaces to implementation instances, implementation types - or providers of implementation instances. There are no XML configuration files, and all - the bindings are type-safe. The container supports injection into instance variables and - constructor parameters based on the <code>@Inject</code> annotation. This mechanism is - very close to Google Guice.</para> - <para>The discussion later in this chapter demonstrates a standalone DI container. But keep in - mind that Cayenne already has a built-in Injector, and a set of default modules. A - Cayenne user would normally only use the API below to write custom extension modules - that will be loaded in that existing container when creating ServerRuntime. See - "Starting and Stopping ServerRuntime" chapter for an example of passing an extension - module to Cayenne.</para> - <para>Cayenne DI probably has ~80% of the features expected in a DI container and has no - dependency on the rest of Cayenne, so in theory can be used as an application-wide DI - engine. But it's primary purpose is still to serve Cayenne. Hence there are no plans to - expand it beyond Cayenne needs. It is an ideal "embedded" DI that does not interfere - with Spring, Guice or any other such framework present elsewhere in the - application.</para> - <section xml:id="di-bindings-api"> - <title>DI Bindings API</title> - <para>To have a working DI container, we need three things: service interfaces and - classes, a module that describes service bindings, a container that loads the - module, and resolves the depedencies. Let's start with service interfaces and - classes:<programlisting language="java">public interface Service1 { - public String getString(); -}</programlisting><programlisting language="java">public interface Service2 { - public int getInt(); -}</programlisting></para> - <para>A service implementation using instance variable - injection:<programlisting language="java">public class Service1Impl implements Service1 { - @Inject - private Service2 service2; - - public String getString() { - return service2.getInt() + "_Service1Impl"; - } -}</programlisting>Same - thing, but using constructor - injection:<programlisting language="java">public class Service1Impl implements Service1 { - - private Service2 service2; - - public Service1Impl(@Inject Service2 service2) { - this.service2 = service2; - } - - public String getString() { - return service2.getInt() + "_Service1Impl"; - } -} -</programlisting><programlisting language="java">public class Service2Impl implements Service2 { - private int i; - - public int getInt() { - return i++; - } -}</programlisting></para> - <para>Now let's create a module implementing - <code>org.apache.cayenne.tutorial.di.Module</code> interface that will contain - DI configuration. A module binds service objects to keys that are reference. Binder - provided by container implements fluent API to connect the key to implementation, - and to configure various binding options (the options, such as scope, are - demonstrated later in this chapter). The simplest form of a key is a Java Class - object representing service interface. Here is a module that binds Service1 and - Service2 to corresponding default implementations:</para> - <para> - <programlisting language="java">public class Module1 implements Module { - - public void configure(Binder binder) { - binder.bind(Service1.class).to(Service1Impl.class); - binder.bind(Service2.class).to(Service2Impl.class); - } -}</programlisting> - </para> - <para>Once we have at least one module, we can create a DI container. - <code>org.apache.cayenne.di.Injector</code> is the container class in - Cayenne:<programlisting language="java">Injector injector = DIBootstrap.createInjector(new Module1());</programlisting></para> - <para>Now that we have created the container, we can obtain services from it and call - their - methods:<programlisting language="java">Service1 s1 = injector.getInstance(Service1.class); -for (int i = 0; i < 5; i++) { - System.out.println("S1 String: " + s1.getString()); -}</programlisting></para> - <para>This outputs the following lines, demonstrating that s1 was Service1Impl and - Service2 injected into it was - Service2Impl:<programlisting language="java">0_Service1Impl -1_Service1Impl -2_Service1Impl -3_Service1Impl -4_Service1Impl</programlisting></para> - <para>There are more flavors of bindings: - <programlisting language="java">// binding to instance - allowing user to create and configure instance -// inside the module class -binder.bind(Service2.class).toInstance(new Service2Impl()); - -// binding to provider - delegating instance creation to a special -// provider class -binder.bind(Service1.class).toProvider(Service1Provider.class); - -// binding to provider instance -binder.bind(Service1.class).toProviderInstance(new Service1Provider()); - -// multiple bindings of the same type using Key -// injection can reference the key name in annotation: -// @Inject("i1") -// private Service2 service2; -binder.bind(Key.get(Service2.class, "i1")).to(Service2Impl.class); -binder.bind(Key.get(Service2.class, "i2")).to(Service2Impl.class);</programlisting></para> - <para>Another types of confiuguration that can be bound in the container are lists and - maps. They will be discussed in the following chapters. </para> - </section> - <section xml:id="managing-services-lifecycle"> - <title>Service Lifecycle</title> - <para>An important feature of the Cayenne DI container is instance <emphasis role="italic" - >scope</emphasis>. The default scope (implicitly used in all examples above) is - "singleton", meaning that a binding would result in creation of only one service - instance, that will be repeatedly returned from - <code>Injector.getInstance(..)</code>, as well as injected into classes that - declare it as a dependency. </para> - <para>Singleton scope dispatches a "BeforeScopeEnd" event to interested services. This - event occurs before the scope is shutdown, i.e. when - <code>Injector.shutdown()</code> is called. Note that the built-in Cayenne - injector is shutdown behind the scenes when <code>ServerRuntime.shutdown()</code> - is invoked. Services may register as listeners for this event by annotating a - no-argument method with <code>@BeforeScopeEnd</code> annotation. Such method should - be implemented if a service needs to clean up some resources, stop threads, - etc.</para> - <para>Another useful scope is "no scope", meaning that every time a container is asked to provide - a service instance for a given key, a new instance will be created and - returned:<programlisting language="java">binder.bind(Service2.class).to(Service2Impl.class).withoutScope();</programlisting>Users - can also create their own scopes, e.g. a web application request scope or a session - scope. Most often than not custom scopes can be created as instances of - <code>org.apache.cayenne.di.spi.DefaultScope</code> with startup and shutdown - managed by the application (e.g. singleton scope is a DefaultScope managed by the - Injector) . </para> - </section> - <section xml:id="overriding-services"> - <title>Overriding Services</title> - <para>Cayenne DI allows to override services already definied in the current module, or - more commonly - some other module in the the same container. Actually there's no - special API to override a service, you'd just bind the service key again with a new - implementation or provider. The last binding for a key takes precedence. This means - that the order of modules is important when configuring a container. The built-in - Cayenne injector ensures that Cayenne standard modules are loaded first, followed by - optional user extension modules. This way the application can override the standard - services in Cayenne.</para> - </section> - </section> - <section xml:id="ways-to-customize-runtime"> - <title> Customization Strategies</title> - <para>The previous section discussed how Cayenne DI works in general terms. Since Cayenne users - will mostly be dealing with an existing Injector provided by ServerRuntime, it is - important to understand how to build custom extensions to a preconfigured container. As - shown in "Starting and Stopping ServerRuntime" chapter, custom extensions are done by - writing an aplication DI module (or multiple modules) that configures service overrides. - This section shows all the configuration possibilities in detail, including changing - properties of the existing services, contributing services to standard service lists and - maps, and overriding service implementations. All the code examples later in this - section are assumed to be placed in an application module "configure" method:</para><programlisting language="java">public class MyExtensionsModule implements Module { - public void configure(Binder binder) { - // customizations go here... - } -}</programlisting><programlisting language="java">Module extensions = new MyExtensionsModule(); -ServerRuntime runtime = ServerRuntime.builder() - .addConfig("com/example/cayenne-mydomain.xml") - .addModule(extensions) - .build();</programlisting> - <section xml:id="changing-properties-of-existing-services"> - <title>Changing Properties of Existing Services</title> - <para>Many built-in Cayenne services change their behavior based on a value of some - environment property. A user may change Cayenne behavior without even knowing which - services are responsible for it, but setting a specific value of a known property. - Supported property names are listed in "Appendix A".</para> - <para>There are two ways to set service properties. The most obvious one is to pass it - to the JVM with -D flag on startup. - E.g.<screen><prompt>$</prompt> java -Dcayenne.server.contexts_sync_strategy=false ...</screen></para> - <para>A second one is to contribute a property to - <code>org.apache.cayenne.configuration.DefaultRuntimeProperties.properties - </code>map (see the next section on how to do that). This map contains the default - property values and can accept application-specific values, overrding the defaults. </para> - <para>Note that if a property value is a name of a Java class, when this Java class is - instantiated by Cayenne, the container performs injection of instance variables. So - even the dynamically specified Java classes can use @Inject annotation to get a hold - of other Cayenne services.</para> - <para>If the same property is specified both in the command line and in the properties - map, the command-line value takes precedence. The map value will be ignored. This - way Cayenne runtime can be reconfigured during deployment.</para> - </section> - <section xml:id="contributing-to-service-lists-maps"> - <title>Contributing to Service Collections</title> - <para>Cayenne can be extended by adding custom objects to named maps or lists bound in - DI. We are calling these lists/maps "service collections". A service collection - allows things like appending a custom strategy to a list of built-in strategies. - E.g. an application that needs to install a custom DbAdapter for some database type - may contribute an instance of custom DbAdapterDetector to a - <code>org.apache.cayenne.configuration.server.DefaultDbAdapterFactory.detectors</code> - list:</para> - <programlisting language="java">public class MyDbAdapterDetector implements DbAdapterDetector { - public DbAdapter createAdapter(DatabaseMetaData md) throws SQLException { - // check if we support this database and retun custom adapter - ... - } -}</programlisting> - <programlisting language="java">// since build-in list for this key is a singleton, repeated -// calls to 'bindList' will return the same instance -binder.bindList(DefaultDbAdapterFactory.DETECTORS_LIST) - .add(MyDbAdapterDetector.class);</programlisting> - <para>Maps are customized using a similar "<code>bindMap</code>" method.</para> - <para>The names of built-in collections are listed in "Appendix B".</para> - </section> - <section xml:id="alternative-service-implementations"> - <title>Alternative Service Implementations</title> - <para>As mentioned above, custom modules are loaded by ServerRuntime after the built-in - modules. So it is easy to redefine a built-in service in Cayenne by rebinding - desired implementations or providers. To do that, first we need to know what those - services to redefine are. While we describe some of them in the following sections, - the best way to get a full list is to check the source code of the Cayenne version - you are using and namely look in - <code>org.apache.cayenne.configuration.server.ServerModule</code> - the main - built-in module in Cayenne. </para> - <para>Now an example of overriding <code>QueryCache</code> service. The default - implementation of this service is provided by <code>MapQueryCacheProvider</code>. - But if we want to use <code>EhCacheQueryCache</code> (a Cayenne wrapper for the - EhCache framework), we can define it like - this:<programlisting language="java">binder.bind(QueryCache.class).to(EhCacheQueryCache.class);</programlisting></para> - </section> - </section> - <section> - <title>Using custom data types</title> - <section> - <title>Value object type</title> - <para> - <code>ValueObjectType</code> is a new and lightweight alternative to the Extended Types API described in the following section. - In most cases is should be preferred as is it easier to understand and use. Currently only one case is known when <code>ExtendedType</code> should be used: - when your value object can be mapped on different JDBC types. - </para> - <para> - In order to use your custom data type you should implement <code>ValueObjectType</code> describing it in terms of some type already known to Cayenne - (e.g. backed by system or user ExtendedType). - </para> - <para> - Let's assume we want to support some data type called <code>Money</code>: - <programlisting language="java"><![CDATA[public class Money { - private BigDecimal value; - - public Money(BigDecimal value) { - this.value = value; - } - - public BigDecimal getValue() { - return value; - } - - // .. some other business logic .. -}]]></programlisting> - Here is how <code>ValueObjectType</code> that will allow to store our <code>Money</code> class as <code>BigDecimal</code> - can be implemented: - <programlisting language="java"><![CDATA[public class MoneyValueObjectType implements ValueObjectType<Money, BigDecimal> { - - @Override - public Class<BigDecimal> getTargetType() { - return BigDecimal.class; - } - - @Override - public Class<Money> getValueType() { - return Money.class; - } - - @Override - public Money toJavaObject(BigDecimal value) { - return new Money(value); - } - - @Override - public BigDecimal fromJavaObject(Money object) { - return object.getValue(); - } - - @Override - public String toCacheKey(Money object) { - return object.getValue().toString(); - } -}]]></programlisting> - </para> - <para> - Last step is to register this new type in <code>ServerRuntime</code>: - <programlisting language="java"><![CDATA[ServerRuntime runtime = ServerRuntime.builder() - .addConfig("cayenne-project.xml") - .addModule(binder -> ServerModule.contributeValueObjectTypes(binder).add(MoneyValueObjectType.class)) - .build();]]></programlisting> - </para> - <para>More examples of implementation you can find in - <link xlink:href="https://github.com/apache/cayenne/tree/STABLE-4.0/cayenne-java8/src/main/java/org/apache/cayenne/java8/access/types";>cayenne-java8 module</link> - </para> - </section> - <section xml:id="extendedtypes"> - <title>Extended Types</title> - <para>JDBC specification defines a set of "standard" database column types (defined in java.sql.Types class) - and a very specific mapping of these types to Java Object Types, such as java.lang.String, - java.math.BigDecimal, etc. Sometimes there is a need to use a custom Java type not known to JDBC driver and - Cayenne allows to configure it. For this Cayenne needs to know how to instantiate this type from - a database "primitive" value, and conversely, how to transform an object of the custom type to - a JDBC-compatible object.</para> - <section xml:id="supporting-non-standard-types"> - <title>Supporting Non-Standard Types</title> - <para>For supporting non-standard type you should define it via an interface <code>org.apache.cayenne.access.types.ExtendedType</code>. - An implementation must provide <code>ExtendedType.getClassName()</code> method that returns - a fully qualified Java class name for the supported custom type, and a number of methods - that convert data between JDBC and custom type. - The following example demonstrates how to add a custom DoubleArrayType - to store <code>java.lang.Double[]</code> as a custom string in a database:</para> - <programlisting language="java"> -/** -* Defines methods to read Java objects from JDBC ResultSets and write as parameters of -* PreparedStatements. -*/ -public class DoubleArrayType implements ExtendedType { - - private final String SEPARATOR = ","; - - /** - * Returns a full name of Java class that this ExtendedType supports. - */ - @Override - public String getClassName() { - return Double[].class.getCanonicalName(); - } - - /** - * Initializes a single parameter of a PreparedStatement with object value. - */ - @Override - public void setJdbcObject(PreparedStatement statement, Object value, - int pos, int type, int scale) throws Exception { - - String str = StringUtils.join((Double[]) value, SEPARATOR); - statement.setString(pos, str); - } - - - /** - * Reads an object from JDBC ResultSet column, converting it to class returned by - * 'getClassName' method. - * - * @throws Exception if read error occurred, or an object can't be converted to a - * target Java class. - */ - @Override - public Object materializeObject(ResultSet rs, int index, int type) throws Exception { - String[] str = rs.getString(index).split(SEPARATOR); - Double[] res = new Double[str.length]; - - for (int i = 0; i < str.length; i++) { - res[i] = Double.valueOf(str[i]); - } - - return res; - } - - /** - * Reads an object from a stored procedure OUT parameter, converting it to class - * returned by 'getClassName' method. - * - * @throws Exception if read error ocurred, or an object can't be converted to a - * target Java class. - */ - @Override - public Object materializeObject(CallableStatement rs, int index, int type) throws Exception { - String[] str = rs.getString(index).split(SEPARATOR); - Double[] res = new Double[str.length]; - - for (int i = 0; i < str.length; i++) { - res[i] = Double.valueOf(str[i]); - } - - return res; - } -} - </programlisting> - <para>For Java7</para> - <programlisting language="java"> -// add DoubleArrayType to list of user types -ServerRuntime runtime = ServerRuntime.builder() - .addConfig("cayenne-project.xml") - .addModule(new Module() { - @Override - public void configure(Binder binder) { - ServerModule.contributeUserTypes(binder).add(new DoubleArrayType()); - } - }) - .build(); - </programlisting> - <para>For Java8</para> - <programlisting language="java"> -// add DoubleArrayType to list of user types -ServerRuntime runtime = ServerRuntime.builder() - .addConfig("cayenne-project.xml") - .addModule(binder -> ServerModule.contributeUserTypes(binder).add(new DoubleArrayType())) - .build(); - </programlisting> - </section> - <section xml:id="dbadapters-and-extended-types"> - <title>DbAdapters and Extended Types</title> - <para>As shown in the example above, ExtendedTypes are stored by DbAdapter. In fact DbAdapters often install - their own extended types to address incompatibilities, incompleteness and differences between - JDBC drivers in handling "standard" JDBC types. For instance some drivers support reading large - character columns (CLOB) as java.sql.Clob, but some other - as "character stream", etc. - Adapters provided with Cayenne override <code>configureExtendedTypes()</code> method to install their own types, - possibly substituting Cayenne defaults. Custom DbAdapters can use the same technique.</para> - </section> - </section> - </section> - <section xml:id="noteworthy-runtime-components"> - <title>Noteworthy Built-in Services</title> - <section xml:id="jdbceventlogger"> - <title>JdbcEventLogger</title> - <para><code>org.apache.cayenne.log.JdbcEventLogger</code> is the service that defines - logging API for Cayenne internals. It provides facilities for logging queries, - commits, transactions, etc. The default implementation is - <code>org.apache.cayenne.log.Slf4jJdbcEventLogger</code> that performs logging - via slf4j-api library. Cayenne library includes another potentially useful - logger - <code>org.apache.cayenne.log.FormattedSlf4jJdbcEventLogger</code> that - produces formatted multiline SQL output that can be easier to read.</para> - </section> - <section xml:id="datasourcefactory"> - <title>DataSourceFactory</title> - <para>Factory that returns <code>javax.sql.DataSource</code> object based on the configuration provided in the - "nodeDescriptor". - </para> - </section> - <section xml:id="datachannelfilter"> - <title>DataChannelFilter</title> - <para> An interface of a filter that allows to intercept DataChannel operations. Filters allow - to implement chains of custom processors around a DataChannel, that can be used for - security, monitoring, business logic, providing context to lifecycle event listeners, - etc. - </para> - </section> - <section xml:id="querycache"> - <title>QueryCache</title> - <para>Defines API of a cache that stores query results.</para> - </section> - </section> -</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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 48e7462..0000000 --- a/docs/docbook/cayenne-guide/src/docbkx/expressions.xml +++ /dev/null @@ -1,303 +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 - to understand the semantics. A Cayenne expression can be represented as a String, which - can be converted to an expression object using <code>ExpressionFactory.exp</code> static - method. Here is an - example:<programlisting language="java">String expString = "name like 'A%' and price < 1000"; -Expression exp = ExpressionFactory.exp(expString);</programlisting>This - particular expression may be used to match Paintings whose names that start with - "A" and whose price is 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 language="SQL">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 case - sensitive and are usually lowercase. Complex words follow the Java camel-case - style:<programlisting language="SQL">// 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 language="SQL">// 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 language="SQL">name like 'A%'</programlisting> - <emphasis role="italic">Parameters.</emphasis> Expressions can contain named parameters - (names that start with "$") that can be substituted with values either by name - or by position. 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 the examples of both positional and - named parameter - bindings:<programlisting language="java">Expression template = ExpressionFactory.exp("name = $name"); -... -// name binding -Map p1 = Collections.singletonMap("name", "Salvador Dali"); -Expression qualifier1 = template.params(p1); -... -// positional binding -Expression qualifier2 = template.paramsArray("Monet");</programlisting></para> - <para>Positional binding is usually shorter. You can pass positional bindings to the - <code>"exp(..)"</code> factory method (its second argument is a params - vararg):<programlisting>Expression qualifier = ExpressionFactory.exp("name = $name", "Monet");</programlisting></para> - <para>In parameterized expressions with LIKE clause, SQL wildcards must be part of the - values in the Map and not the expression string - itself:<programlisting language="java">Expression qualifier = ExpressionFactory.exp("name like $name", "Salvador%");</programlisting>When - matching on a relationship, the value parameter must be either a Persistent object, an - <code>org.apache.cayenne.ObjectId</code>, or a numeric ID value (for single column - IDs). - E.g.:<programlisting language="java">Artist dali = ... // asume we fetched this one already -Expression qualifier = ExpressionFactory.exp("artist = $artist", dali);</programlisting>When - using positional binding, Cayenne would expect values for <emphasis role="bold" - >all</emphasis> parameters to be present. Binding by name offers extra flexibility: - subexpressions with uninitialized parameters are automatically pruned from the - expression. So e.g. if certain parts of the expression criteria are not provided to the - application, you can still build a valid - expression:<programlisting language="java">Expression template = ExpressionFactory.exp("name like $name and dateOfBirth > $date"); -... -Map p1 = Collections.singletonMap("name", "Salvador%"); -Expression qualifier1 = template.params(p1); - -// "qualifier1" is now "name like 'Salvador%'". -// 'dateOfBirth > $date' 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 are 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 the expression grammar is provided in Appendix C</para> - </note> - </para> - </section> - <section xml:id="expressions-with-expressionfactory"> - <title>Creating Expressions via API</title> - <para>Creating expressions from Strings is a powerful and dynamic approach, however a safer - alternative is to use Java API. It provides compile-time checking of expressions - validity. The API in question is provided by <code>ExpressionFactory</code> class (that - we've seen already), <code>Property</code> class and <code>Expression</code> class - itself. <code>ExpressionFactory</code> contains a number of self-explanatory static - methods that can be used to build expressions. E.g.:</para> - <para> - <programlisting language="java">// String expression: name like 'A%' and price < 1000 -Expression e1 = ExpressionFactory.likeExp("name", "A%"); -Expression e2 = ExpressionFactory.lessExp("price, 1000); -Expression finalExp = e1.andExp(e2); </programlisting> - <note> - <para>The last line in the example above shows how to create a new expression by - "chaining" two 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 language="java">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. - <code>"|exhibits.paintings"</code>, <code>"exhibits|paintings"</code>, etc. - Internally Cayenne would generate distinct aliases for each of the split expressions, - forcing separate joins.</para> - <para>While ExpressionFactory is pretty powerful, there's an even easier way to create - expression using static Property objects generated by Cayenne for each persistent class. - Some - examples:<programlisting>// Artist.NAME is generated by Cayenne and has a type of Property<String> -Expression e1 = Artist.NAME.eq("Pablo"); - -// Chaining multiple properties into a path.. -// Painting.ARTIST is generated by Cayenne and has a type of Property<Artist> -Expression e2 = Painting.ARTIST.dot(Artist.NAME).eq("Pablo");</programlisting></para> - <para>Property objects provide the API mostly analogius to ExpressionFactory, though it is - significantly shorter and is aware of the value types. It provides compile-time checks - of both property names and types of arguments in conditions. We will use Property-based - API in further examples.</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 language="java">Expression e = Artist.NAME.in("John", "Bob"); -Artist artist = ... -if(e.match(artist)) { - ... -}</programlisting>Reading - property - value:<programlisting language="java">String name = Artist.NAME.path().evaluate(artist);</programlisting></para> - <para>Filtering a list of - objects:<programlisting language="java">Expression e = Artist.NAME.in("John", "Bob"); -List<Artist> unfiltered = ... -List<Artist> 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> - - <section xml:id="expressions-to-ejbql"> - <title>Translating Expressions to EJBQL</title> - <para> - <link linkend="ejbqlquery">EJBQL</link> is a textual query language that can be used - with Cayenne. In some situations, it is convenient to be able to convert Expression - instances into EJBQL. Expressions support this conversion. An example is shown below. - <programlisting language="java">String serial = ... -Expression e = Pkg.SERIAL.eq(serial); -List<Object> params = new ArrayList<Object>(); -EJBQLQuery query = new EJBQLQuery("SELECT p FROM Pkg p WHERE " + e.toEJBQL(params,"p"); - -for(int i=0;i<params.size();i++) { - query.setParameter(i+1, params.get(i)); -}</programlisting> - This would be equivalent to the following purely EJBQL querying logic; - <programlisting language="java">EJBQLQuery query = new EJBQLQuery("SELECT p FROM Pkg p WHERE p.serial = ?1"); -query.setParameter(1,serial);</programlisting> - </para> - </section> -</chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/ext-cache-invalidation.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-cache-invalidation.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-cache-invalidation.xml deleted file mode 100644 index f3e0a0d..0000000 --- a/docs/docbook/cayenne-guide/src/docbkx/ext-cache-invalidation.xml +++ /dev/null @@ -1,91 +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="ext-cache-invalidation"> - <title>Cache invalidation extension</title> - <section> - <title>Description</title> - <para>Cache invalidation module is an extension that allows to define cache invalidation policy programmatically.</para> - </section> - <section> - <title>Including in a project</title> - <section> - <title>Maven</title> - <para> - <programlisting language="xml"><dependency> - <groupId>org.apache.cayenne</groupId> - <artifactId>cayenne-cache-invalidation</artifactId> - <version><?eval ${project.version}?></version> -</dependency></programlisting> - </para> - </section> - <section> - <title>Gradle</title> - <para> - <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-cache-invalidation:<?eval ${project.version}?>'</programlisting> - </para> - </section> - </section> - <section> - <title>Usage</title> - <para> - Module supports autoloading mechanism, so no other actions required to enable it. - Just mark your entities with <code>@CacheGroups</code> annotation and you are ready to use it: - <programlisting language="java"><![CDATA[ -@CacheGroups("some-group") -public class MyEntity extends _MyEntity { - // ... -}]]></programlisting> - After any modification of <code>MyEntity</code> objects cache group <code>"some-group"</code> - will be dropped from cache automatically. - <note> - <para>You can read more about cache and cache groups in corresponding <link linkend="caching-and-fresh-data">chapter</link> of this documentation.</para> - </note> - </para> - <para> - In case you need some complex logic of cache invalidation you can disable default behaviour and provide your own. - </para> - <para> - To do so you need to implement <code>org.apache.cayenne.cache.invalidation.InvalidationHandler</code> interface and setup Cache Invalidation module to - use it. - Let's use implementation class called <code>CustomInvalidationHandler</code> that will simply match - all entities' types with <code>"custom-group"</code> cache group regardless of any annotations: - <programlisting language="java"><![CDATA[ -public class CustomInvalidationHandler implements InvalidationHandler { - @Override - public InvalidationFunction canHandle(Class<? extends Persistent> type) { - return p -> Collections.singleton(new CacheGroupDescriptor("custom-group")); - } -}]]></programlisting> - Now we'll set up it's usage by <code>ServerRuntime</code>: - <programlisting language="java"><![CDATA[ -ServerRuntime.builder() - .addModule(CacheInvalidationModule.extend() - // this will disable default handler based on @CacheGroups, and this is optional - .noCacheGroupsHandler() - .addHandler(CustomInvalidationHandler.class) - .module()) -]]></programlisting> - <note> - <para>You can combine as many invalidation handlers as you need.</para> - </note> - </para> - </section> -</chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/ext-commit-log.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-commit-log.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-commit-log.xml deleted file mode 100644 index 20aec52..0000000 --- a/docs/docbook/cayenne-guide/src/docbkx/ext-commit-log.xml +++ /dev/null @@ -1,89 +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="ext-commit-log"> - <title>Commit log extension</title> - <section> - <title>Description</title> - <para>The goal of this module is to capture commit changes and present them to interested parties in an easy-to-process format.</para> - </section> - <section> - <title>Including in a project</title> - <section> - <title>Maven</title> - <para> - <programlisting language="xml"><dependency> - <groupId>org.apache.cayenne</groupId> - <artifactId>cayenne-commitlog</artifactId> - <version><?eval ${project.version}?></version> -</dependency></programlisting> - </para> - </section> - <section> - <title>Gradle</title> - <para> - <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-commitlog:<?eval ${project.version}?>'</programlisting> - </para> - </section> - </section> - <section> - <title>Usage</title> - <para> - In order to use <code>commitlog</code> module you need to perform three steps: - <orderedlist> - <listitem> - <para>Mark all entities which changes you are interested in with <code>@org.apache.cayenne.commitlog.CommitLog</code> annotation</para> - <programlisting language="java"><![CDATA[ -@CommitLog(ignoredProperties = {"somePrivatePropertyToSkip"}) -public class MyEntity extends _MyEntity { - // ... -}]]></programlisting> - </listitem> - <listitem> - <para> - Implement <code>CommitLogListener</code> interface. - <programlisting language="java"><![CDATA[ -public class MyCommitLogListener implements CommitLogListener { - @Override - public void onPostCommit(ObjectContext originatingContext, ChangeMap changes) { - // ChangeMap will contain all information about changes happened in performed commit - // this particular example will print IDs of all inserted objects - changes.getUniqueChanges().stream() - .filter(change -> change.getType() == ObjectChangeType.INSERT) - .map(ObjectChange::getPostCommitId) - .forEach(id -> System.out.println("Inserted new entity with id: " + id)); - } -}]]></programlisting> - </para> - </listitem> - <listitem> - <para> - Inject your listener into <code>ServerRuntime</code> - <programlisting language="java"><![CDATA[ -ServerRuntime.builder() - .addModule(CommitLogModule.extend() - .addListener(MyCommitLogListener.class) - .module())]]></programlisting> - </para> - </listitem> - </orderedlist> - </para> - </section> -</chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/ext-crypto.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-crypto.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-crypto.xml deleted file mode 100644 index 8381bab..0000000 --- a/docs/docbook/cayenne-guide/src/docbkx/ext-crypto.xml +++ /dev/null @@ -1,135 +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="ext-crypto"> - <title>Crypto extension</title> - <section> - <title>Description</title> - <para>Crypto module allows encrypt and decrypt values stored in DB transparently to your Java app.</para> - </section> - <section> - <title>Including in a project</title> - <section> - <title>Maven</title> - <para> - <programlisting language="xml"><dependency> - <groupId>org.apache.cayenne</groupId> - <artifactId>cayenne-crypto</artifactId> - <version><?eval ${project.version}?></version> -</dependency></programlisting> - </para> - </section> - <section> - <title>Gradle</title> - <para> - <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-crypto:<?eval ${project.version}?>'</programlisting> - </para> - </section> - </section> - <section> - <title>Usage</title> - <section> - <title>Setup your model and DB</title> - <para> - To use crypto module you must prepare your database to allow <code>byte[]</code> storage and properly name - columns that will contain encrypted values. - </para> - <para> - Currently supported SQL types that can be used to store encrypted data are: - <orderedlist> - <listitem> - <para> - Binary types: <code>BINARY, BLOB, VARBINARY, LONGVARBINARY</code>. - These types are preferred. - </para> - </listitem> - <listitem> - <para>Character types, that will store <code>base64</code> encoded value: - <code>CHAR, NCHAR, CLOB, NCLOB, LONGVARCHAR, LONGNVARCHAR, VARCHAR, NVARCHAR</code></para> - </listitem> - </orderedlist> - <note> - <para>Not all data types may be supported by your database.</para> - </note> - </para> - <para> - Default naming strategy that doesn't require additional setup suggests using <code>"CRYPTO_"</code> prefix. - You can change this default strategy by injecting you own implementation of - <code>org.apache.cayenne.crypto.map.ColumnMapper</code> interface. - <programlisting language="java"><![CDATA[ -ServerRuntime.builder() - .addModule(CryptoModule.extend() - .columnMapper(MyColumnMapper.class) - .module())]]></programlisting> - </para> - <para> - Here is an example of how <code>ObjEntity</code> with two encrypted and two unencrypted properties - can look like: - </para> - <para><inlinemediaobject> - <imageobject> - <imagedata fileref="images/ext-crypto-obj-entity.png" scalefit="1" width="100%"/> - </imageobject> - </inlinemediaobject></para> - </section> - <section> - <title>Setup keystore</title> - <para> - To perform encryption you must provide <code>KEYSTORE_URL</code> and <code>KEY_PASSWORD</code>. - Currently crypto module supports only Java "jceks" KeyStore. - <programlisting language="java"><![CDATA[ -ServerRuntime.builder() - .addModule(CryptoModule.extend() - .keyStore(this.getClass().getResource("keystore.jcek"), "my-password".toCharArray(), "my-key-alias") - .module())]]></programlisting> - </para> - </section> - <section> - <title>Additional settings</title> - <para> - Additionally to <code>ColumnMapper</code> mentioned above you can customize other parts of - <code>crypto module</code>. - You can enable <code>gzip</code> compression and <code>HMAC</code> usage (later will ensure integrity of data). - <programlisting language="java"><![CDATA[ -ServerRuntime.builder() - .addModule(CryptoModule.extend() - .compress() - .useHMAC() - .module())]]></programlisting> - </para> - <para> - Another useful extension point is support for custom Java value types. To add support for your - data type you need to implement <code>org.apache.cayenne.crypto.transformer.value.BytesConverter</code> - interface that will convert required type to and from <code>byte[]</code>. - <programlisting language="java"><![CDATA[ -ServerRuntime.builder() - .addModule(CryptoModule.extend() - .objectToBytesConverter(MyClass.class, new MyClassBytesConverter()) - .module())]]></programlisting> - </para> - <note> - <para>In addition to Java primitive types (and their object counterparts), <code>crypto module</code> - supports encryption only of <code>java.util.Date</code>, <code>java.math.BigInteger</code> - and <code>java.math.BigDecimal</code> types. - </para> - </note> - </section> - </section> -</chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/ext-dbcp2.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-dbcp2.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-dbcp2.xml deleted file mode 100644 index 715ebc6..0000000 --- a/docs/docbook/cayenne-guide/src/docbkx/ext-dbcp2.xml +++ /dev/null @@ -1,59 +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="ext-dbcp2"> - <title>Apache Commons DBCP integration</title> - <section> - <title>Description</title> - <para> - This module enables usage of Apache Commons DBCP2 connection pool. - </para> - </section> - <section> - <title>Including in a project</title> - <section> - <title>Maven</title> - <para> - <programlisting language="xml"><dependency> - <groupId>org.apache.cayenne</groupId> - <artifactId>cayenne-dbcp2</artifactId> - <version><?eval ${project.version}?></version> -</dependency></programlisting> - </para> - </section> - <section> - <title>Gradle</title> - <para> - <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-dbcp2:<?eval ${project.version}?>'</programlisting> - </para> - </section> - </section> - <section> - <title>Usage</title> - <para> - To use DBCP2 pool you need to setup it in <code>DataNode</code> settings in Cayenne Modeler: - </para> - <para><inlinemediaobject> - <imageobject> - <imagedata fileref="images/ext-dbcp-setup.png" scalefit="1" width="100%"/> - </imageobject> - </inlinemediaobject></para> - </section> -</chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/ext-java8.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-java8.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-java8.xml deleted file mode 100644 index 9ee1e70..0000000 --- a/docs/docbook/cayenne-guide/src/docbkx/ext-java8.xml +++ /dev/null @@ -1,53 +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="ext-java8"> - <title>Java 8 extension</title> - <section> - <title>Description</title> - <para>Java 8 module allows to use <code>java.time.LocalTime</code>, <code>java.time.LocalDate</code> - and <code>java.time.LocalDateTime</code> types for entity attributes</para> - </section> - <section> - <title>Including in a project</title> - <section> - <title>Maven</title> - <para> - <programlisting language="xml"><dependency> - <groupId>org.apache.cayenne</groupId> - <artifactId>cayenne-java8</artifactId> - <version><?eval ${project.version}?></version> -</dependency></programlisting> - </para> - </section> - <section> - <title>Gradle</title> - <para> - <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-java8:<?eval ${project.version}?>'</programlisting> - </para> - </section> - </section> - <section> - <title>Usage</title> - <para> - This module doesn't require any additional setup, you can just use new data types in your model. - </para> - </section> -</chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/ext-jcache.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-jcache.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-jcache.xml deleted file mode 100644 index 509d538..0000000 --- a/docs/docbook/cayenne-guide/src/docbkx/ext-jcache.xml +++ /dev/null @@ -1,61 +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="ext-jcache"> - <title>JCache integration</title> - <section> - <title>Description</title> - <para>This module allows to integrate any JCache (JSR 107) compatible caching provider with Cayenne.</para> - </section> - <section> - <title>Including in a project</title> - <section> - <title>Maven</title> - <para> - <programlisting language="xml"><dependency> - <groupId>org.apache.cayenne</groupId> - <artifactId>cayenne-jcache</artifactId> - <version><?eval ${project.version}?></version> -</dependency></programlisting> - </para> - </section> - <section> - <title>Gradle</title> - <para> - <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-jcache:<?eval ${project.version}?>'</programlisting> - </para> - </section> - </section> - <section> - <title>Usage</title> - <para> - To use JCache provider in your app you need to include this module and caching provider libs (e.g. Ehcache). - You can provide own implementation of <code>org.apache.cayenne.jcache.JCacheConfigurationFactory</code> - to customize cache configuration if required. - </para> - <para> - For advanced configuration and management please use provider specific options and tools. - </para> - <note> - <para>You can read about using cache in Cayenne in <link linkend="caching-and-fresh-data">this</link> chapter.</para> - <para>You may else be interested in <link linkend="ext-cache-invalidation">cache invalidation</link> extension.</para> - </note> - </section> -</chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/ext-joda.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-joda.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-joda.xml deleted file mode 100644 index d777b68..0000000 --- a/docs/docbook/cayenne-guide/src/docbkx/ext-joda.xml +++ /dev/null @@ -1,53 +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="ext-joda"> - <title>Joda time extension</title> - <section> - <title>Description</title> - <para>Joda time module allows to use <code>org.joda.time.LocalTime</code>, <code>org.joda.time.LocalDate</code>, - <code>org.joda.time.LocalDateTime</code> and <code>org.joda.time.DateTime</code> types for entity attributes</para> - </section> - <section> - <title>Including in a project</title> - <section> - <title>Maven</title> - <para> - <programlisting language="xml"><dependency> - <groupId>org.apache.cayenne</groupId> - <artifactId>cayenne-joda</artifactId> - <version><?eval ${project.version}?></version> -</dependency></programlisting> - </para> - </section> - <section> - <title>Gradle</title> - <para> - <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-joda:<?eval ${project.version}?>'</programlisting> - </para> - </section> - </section> - <section> - <title>Usage</title> - <para> - This module doesn't require any additional setup, you can just use new data types in your model. - </para> - </section> -</chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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/cde78f0b/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>
