Repository: cayenne Updated Branches: refs/heads/master bdcd78a90 -> 36e23224d
Update README Project: http://git-wip-us.apache.org/repos/asf/cayenne/repo Commit: http://git-wip-us.apache.org/repos/asf/cayenne/commit/36e23224 Tree: http://git-wip-us.apache.org/repos/asf/cayenne/tree/36e23224 Diff: http://git-wip-us.apache.org/repos/asf/cayenne/diff/36e23224 Branch: refs/heads/master Commit: 36e23224dec8c85064bc6d209b06e069b3d86381 Parents: bdcd78a Author: Nikita Timofeev <stari...@gmail.com> Authored: Mon Jul 30 11:55:27 2018 +0300 Committer: Nikita Timofeev <stari...@gmail.com> Committed: Mon Jul 30 11:55:27 2018 +0300 ---------------------------------------------------------------------- README.md | 222 ++++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 190 insertions(+), 32 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cayenne/blob/36e23224/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index 32728e6..2143262 100644 --- a/README.md +++ b/README.md @@ -31,17 +31,124 @@ Apache Cayenne [Apache Cayenne](https://cayenne.apache.org) is an open source persistence framework licensed under the Apache License, providing object-relational mapping (ORM) and remoting services. +Table Of Contents +----------------- + +* [Quick Start](#quick-start) + * [Create Project](#create-xml-mapping) + * [Cayenne Modeler](#modeler-gui-application) + * [Maven plugin](#maven-plugin) + * [Gradle plugin](#gradle-plugin) + * [Include Cayenne Into Project](#include-cayenne-into-project) + * [Create Cayenne Runtime](#create-cayenne-runtime) + * [Create New Objects](#create-new-objects) + * [Queries](#queries) + * [Select Objects](#select-objects) + * [Aggregate Functions](#aggregate-functions) + * [Raw SQL queries](#raw-sql-queries) +* [Documentation](#documentation) +* [About](#about) +* [License](#license) +* [Collaboration](#collaboration) + + Quick Start ---------------- -#### Modeler GUI application +#### Create XML mapping + +##### Modeler GUI application -To create Cayenne project you will need Cayenne Modeler. -You can download it from https://cayenne.apache.org/download/ +You can use Cayenne Modeler to manually create Cayenne project without DB. +Binary distributions can be downloaded from https://cayenne.apache.org/download/ [](https://cayenne.apache.org/download/) -See tutorial https://cayenne.apache.org/docs/4.0/getting-started-guide/ +See tutorial https://cayenne.apache.org/docs/4.1/getting-started-guide/ + +##### Maven plugin + +Additionally you can use Cayenne Maven (or [Gradle](#gradle-plugin)) plugin to create model based on existing DB structure. +Here is example of Cayenne Maven plugin setup that will do it: + +```xml +<plugin> + <groupId>org.apache.cayenne.plugins</groupId> + <artifactId>cayenne-maven-plugin</artifactId> + <version>4.1.M2</version> + + <dependencies> + <dependency> + <groupId>mysql</groupId> + <artifactId>mysql-connector-java</artifactId> + <version>6.0.5</version> + </dependency> + </dependencies> + + <configuration> + <map>${project.basedir}/src/main/resources/demo.map.xml</map> + <cayenneProject>${project.basedir}/src/main/resources/cayenne-demo.xml</cayenneProject> + <dataSource> + <url>jdbc:mysql://localhost:3306/cayenne_demo</url> + <driver>com.mysql.jdbc.Driver</driver> + <username>user</username> + <password>password</password> + </dataSource> + <dbImport> + <defaultPackage>org.apache.cayenne.demo.model</defaultPackage> + </dbImport> + </configuration> +</plugin> +``` + +Run it: +```bash +mvn cayenne:cdbimport +mvn cayenne:cgen +``` +See tutorial https://cayenne.apache.org/docs/4.1/getting-started-db-first/ + +##### Gradle plugin + +And here is example of Cayenne Gradle plugin setup: + +```groovy +buildscript { + repositories { + mavenCentral() + } + dependencies { + classpath group: 'org.apache.cayenne.plugins', name: 'cayenne-gradle-plugin', version: '4.1.M2' + classpath 'mysql:mysql-connector-java:6.0.5' + } +} + +apply plugin: 'org.apache.cayenne' +cayenne.defaultDataMap 'demo.map.xml' + +cdbimport { + cayenneProject 'cayenne-demo.xml' + + dataSource { + driver 'com.mysql.cj.jdbc.Driver' + url 'jdbc:mysql://127.0.0.1:3306/cayenne_demo' + username 'user' + password 'password' + } + + dbImport { + defaultPackage = 'org.apache.cayenne.demo.model' + } +} + +cgen.dependsOn cdbimport +compileJava.dependsOn cgen +``` + +Run it: +```bash +gradlew build +``` #### Include Cayenne into project @@ -52,12 +159,7 @@ See tutorial https://cayenne.apache.org/docs/4.0/getting-started-guide/ <dependency> <groupId>org.apache.cayenne</groupId> <artifactId>cayenne-server</artifactId> - <version>4.0.RC1</version> - </dependency> - <dependency> - <groupId>org.apache.cayenne</groupId> - <artifactId>cayenne-java8</artifactId> - <version>4.0.RC1</version> + <version>4.1.M2</version> </dependency> </dependencies> ``` @@ -65,15 +167,17 @@ See tutorial https://cayenne.apache.org/docs/4.0/getting-started-guide/ ##### Gradle ```groovy -compile group: 'org.apache.cayenne', name: 'cayenne-server', version: '4.0.RC1' -compile group: 'org.apache.cayenne', name: 'cayenne-java8', version: '4.0.RC1' +compile group: 'org.apache.cayenne', name: 'cayenne-server', version: '4.1.M2' + +// or, if Gradle plugin is used +compile cayenne.dependency('server') ``` #### Create Cayenne Runtime ```java ServerRuntime cayenneRuntime = ServerRuntime.builder() - .addConfig("cayenne-project.xml") + .addConfig("cayenne-demo.xml") .build(); ``` @@ -86,30 +190,79 @@ Artist picasso = context.newObject(Artist.class); picasso.setName("Pablo Picasso"); picasso.setDateOfBirth(LocalDate.of(1881, 10, 25)); +Gallery metropolitan = context.newObject(Gallery.class); +metropolitan.setName("Metropolitan Museum of Art"); + Painting girl = context.newObject(Painting.class); girl.setName("Girl Reading at a Table"); -girl.setArtist(picasso); + +Painting stein = context.newObject(Painting.class); +stein.setName("Gertrude Stein"); + +picasso.addToPaintings(girl); +picasso.addToPaintings(stein); + +girl.setGallery(metropolitan); +stein.setGallery(metropolitan); context.commitChanges(); ``` -#### Select Objects +#### Queries -```java -// Single object select with order -Artist artist = ObjectSelect.query(Artist.class) - .orderBy(Artist.NAME.asc()) - .selectFirst(context); +##### Select Objects -// Select with join +```java List<Painting> paintings = ObjectSelect.query(Painting.class) .where(Painting.ARTIST.dot(Artist.DATE_OF_BIRTH).lt(LocalDate.of(1900, 1, 1))) + .prefetch(Painting.ARTIST.joint()) .select(context); +``` + +##### Aggregate functions + +```java +// this is artificial property signaling that we want to get full object +Property<Artist> artistProperty = Property.createSelf(Artist.class); + +List<Object[]> artistAndPaintingCount = ObjectSelect.columnQuery(Artist.class, artistProperty, Artist.PAINTING_ARRAY.count()) + .where(Artist.ARTIST_NAME.like("a%")) + .having(Artist.PAINTING_ARRAY.count().lt(5L)) + .orderBy(Artist.PAINTING_ARRAY.count().desc(), Artist.ARTIST_NAME.asc()) + .select(context); + +for(Object[] next : artistAndPaintingCount) { + Artist artist = (Artist)next[0]; + long paintingsCount = (Long)next[1]; + System.out.println(artist.getArtistName() + " has " + paintingsCount + " painting(s)"); +} + +``` + +##### Raw SQL queries + +```java +// Selecting objects +List<Painting> paintings = SQLSelect + .query(Painting.class, "SELECT * FROM PAINTING WHERE PAINTING_TITLE LIKE #bind($title)") + .params("title", "painting%") + .upperColumnNames() + .localCache() + .limit(100) + .select(context); + +// Selecting scalar values +List<String> paintingNames = SQLSelect + .scalarQuery(String.class, "SELECT PAINTING_TITLE FROM PAINTING WHERE ESTIMATED_PRICE > #bind($price)") + .params("price", 100000) + .select(context); + +// Insert values +int inserted = SQLExec + .query("INSERT INTO ARTIST (ARTIST_ID, ARTIST_NAME) VALUES (#bind($id), #bind($name))") + .paramsArray(55, "Picasso") + .update(context); -// Select count -long count = ObjectSelect.query(Painting.class) - .where(Painting.ESTIMATED_PRICE.gt(10000)) - .selectCount(context); ``` Documentation @@ -117,15 +270,19 @@ Documentation #### Getting Started -https://cayenne.apache.org/docs/4.0/getting-started-guide/ +https://cayenne.apache.org/docs/4.1/getting-started-guide/ + +#### Getting Started Db-First + +https://cayenne.apache.org/docs/4.1/getting-started-db-first/ #### Full documentation -https://cayenne.apache.org/docs/4.0/cayenne-guide/ +https://cayenne.apache.org/docs/4.1/cayenne-guide/ #### JavaDoc -https://cayenne.apache.org/docs/4.0/api/ +https://cayenne.apache.org/docs/4.1/api/ About ----- @@ -136,13 +293,14 @@ Cayenne is designed to be easy to use, without sacrificing flexibility or design Cayenne supports numerous other features, including caching, a complete object query syntax, relationship pre-fetching, on-demand object and relationship faulting, object inheritance, database auto-detection, and generic persisted objects. Most importantly, Cayenne can scale up or down to virtually any project size. With a mature, 100% open source framework, an energetic user community, and a track record of solid performance in high-volume environments, Cayenne is an exceptional choice for persistence services. -License ---------- -Cayenne is available as free and open source under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). - Collaboration -------------- * [Bug/Feature Tracker](https://issues.apache.org/jira/browse/CAY) * [Mailing lists](https://cayenne.apache.org/mailing-lists.html) * [Support](https://cayenne.apache.org/support.html) +* [Contributing](https://cayenne.apache.org/how-can-i-help.html) + +License +--------- +Cayenne is available as free and open source under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).
