If you are planning on using several RDBMS (= SQLDialects) or several distinct JDBC Connections in your software, this will mean that you have to create a new Factory every time.
+Factory settings
++ The jOOQ Factory allows for some optional configuration elements to be used by advanced users. + The Settings class is a JAXB-annotated + type. In future releases of jOOQ, these settings can be loaded from an XML file automatically. + Subsequent sections of the manual contain some more in-depth explanations about these settings: +
+-
+
+
- + +Runtime schema and table mapping + + + +
- + +Execute listeners and SQL tracing + + + +
+ Please refer to the jOOQ runtime configuration XSD for more details:
+
+http://www.jooq.org/xsd/jooq-runtime-2.0.5.xsd
+
+
Factory subclasses
There are a couple of subclasses for the general Factory. Each SQL @@ -1227,6 +1260,9 @@ Object[] fetchArray(String fieldName); // Fetch a Cursor for lazy iteration Cursor<R> fetchLazy(); +// Or a JDBC ResultSet, if you prefer that +ResultSet fetchResultSet(); + // Fetch data asynchronously and let client code // decide, when the data must be available. // This makes use of the java.util.concurrent API, @@ -1621,17 +1657,6 @@ public void bind(BindContext context) throws DataAccessException; </jdbc> <generator> - <!-- The default code generator. You can override this one, to generate your own code style - Defaults to org.jooq.util.DefaultGenerator --> - <name>org.jooq.util.DefaultGenerator</name> - - <!-- The naming strategy used for class and field names. - You may override this with your custom naming strategy. - Defaults to org.jooq.util.DefaultGeneratorStrategy --> - <strategy> - <name>org.jooq.util.DefaultGeneratorStrategy</name> - </strategy> - <database> <!-- The database dialect from jooq-meta. Available dialects are named org.util.[database].[database]Database. Known values are: @@ -1687,97 +1712,10 @@ public void bind(BindContext context) throws DataAccessException; </generator> </configuration> -
And you can add some optional advanced configuration parameters for the database:
- -<!-- These properties can be added to the database element: --> -<database> - <!-- Generate java.sql.Timestamp fields for DATE columns. This is - particularly useful for Oracle databases. - Defaults to false --> - <dateAsTimestamp>false</dateAsTimestamp> - - <!-- Generate jOOU data types for your unsigned data types, which are - not natively supported in Java. - Defaults to true --> - <unsignedTypes>true</unsignedTypes> - - <!-- The schema that is used in generated source code. This will be the - production schema. Use this to override your local development - schema name for source code generation. If not specified, this - will be the same as the input-schema. --> - <outputSchema>[your database schema / owner / name]</outputSchema> - - <!-- A configuration element to configure several input and/or output - schemata for jooq-meta, in case you're using jooq-meta in a multi- - schema environment. - This cannot be combined with the above inputSchema / outputSchema --> - <schemata> - <schema> - <inputSchema>...</inputSchema> - <outputSchema>...</outputSchema> - </schema> - [ <schema>...</schema> ... ] - </schemata> - - <!-- A configuration element to configure master data table enum classes --> - <masterDataTables>...</masterDataTables> - - <!-- A configuration element to configure synthetic enum types - This is EXPERIMENTAL functionality. Use at your own risk --> - <enumTypes>...</enumTypes> - - <!-- A configuration element to configure type overrides for generated - artefacts (e.g. in combination with enumTypes) - This is EXPERIMENTAL functionality. Use at your own risk --> - <forcedTypes>...</forcedTypes> -</database>- -
Also, you can add some optional advanced configuration parameters for the generator:
- -<!-- These properties can be added to the generate element: --> -<generate> - <!-- Primary key / foreign key relations should be generated and used. - This is a prerequisite for various advanced features. - Defaults to false --> - <relations>false</relations> - - <!-- Generate navigation methods to navigate foreign key relationships - directly from Record classes. This is only relevant if relations - is set to true, too. - Defaults to true --> - <navigationMethods>true</navigationMethods> - - <!-- Generate deprecated code for backwards compatibility - Defaults to true --> - <deprecated>true</deprecated> - - <!-- Generate instance fields in your tables, as opposed to static - fields. This simplifies aliasing. - Defaults to true --> - <instanceFields>true</instanceFields> - - <!-- Generate the javax.annotation.Generated annotation to indicate - jOOQ version used for source code. - Defaults to true --> - <generatedAnnotation>true</generatedAnnotation> - - <!-- Generate POJOs in addition to Record classes for usage of the - ResultQuery.fetchInto(Class) API - Defaults to false --> - <pojos>false</pojos> - - <!-- Annotate POJOs and Records with JPA annotations for increased - compatibility and better integration with JPA/Hibernate, etc - Defaults to false --> - <jpaAnnotations>false</jpaAnnotations> -</generate>- -
Check out the manual's section about - master data - to find out more - about those advanced configuration parameters.
- -Also, check out the official XSD file at +
+ There are also lots of advanced configuration parameters, which will be + treated in the manual's next section + Note, you can find the official XSD file at http://www.jooq.org/xsd/jooq-codegen-2.0.4.xsd for a formal specification
@@ -1958,8 +1896,210 @@ public void bind(BindContext context) throws DataAccessException;Be sure, both jOOQ.jar and your generated package (see configuration) are located on your classpath. Once this is done, you can execute SQL statements with your generated classes.
++2.2. Advanced configuration of the generator
jOOQ power users may want to fine-tune their source code generation settings. Here's how to do this
+Code generation
++ In the previous section + we have seen how jOOQ's source code generator is configured and + run within a few steps. In this chapter we'll treat some advanced + settings +
+ +<!-- These properties can be added directly to the generator element: --> +<generator> + <!-- The default code generator. You can override this one, to generate your own code style + Defaults to org.jooq.util.DefaultGenerator --> + <name>org.jooq.util.DefaultGenerator</name> + + <!-- The naming strategy used for class and field names. + You may override this with your custom naming strategy. Some examples follow + Defaults to org.jooq.util.DefaultGeneratorStrategy --> + <strategy> + <name>org.jooq.util.DefaultGeneratorStrategy</name> + </strategy> +</generator>+ +
+ The following example shows how you can override the + DefaultGeneratorStrategy to render table and column names the way + they are defined in the database, rather than switching them to + camel case: +
+ +/**
+ * It is recommended that you extend the DefaultGeneratorStrategy. Most of the
+ * GeneratorStrategy API is already declared final. You only need to override any
+ * of the following methods, for whatever generation behaviour you'd like to achieve
+ *
+ * Beware that most methods also receive a "Mode" object, to tell you whether a
+ * TableDefinition is being rendered as a Table, Record, POJO, etc. Depending on
+ * that information, you can add a suffix only for TableRecords, not for Tables
+ */
+public class AsInDatabaseStrategy extends DefaultGeneratorStrategy {
+
+ /**
+ * Override this to specifiy what identifiers in Java should look like.
+ * This will just take the identifier as defined in the database.
+ */
+ @Override
+ public String getJavaIdentifier(Definition definition) {
+ return definition.getOutputName();
+ }
+
+ /**
+ * Override these to specify what a setter in Java should look like. Setters
+ * are used in TableRecords, UDTRecords, and POJOs. This example will name
+ * setters "set[NAME_IN_DATABASE]"
+ */
+ @Override
+ public String getJavaSetterName(Definition definition, Mode mode) {
+ return "set" + definition.getOutputName();
+ }
+
+ /**
+ * Just like setters...
+ */
+ @Override
+ public String getJavaGetterName(Definition definition, Mode mode) {
+ return "get" + definition.getOutputName();
+ }
+
+ /**
+ * Override this method to define what a Java method generated from a database
+ * Definition should look like. This is used mostly for convenience methods
+ * when calling stored procedures and functions. This example shows how to
+ * set a prefix to a CamelCase version of your procedure
+ */
+ @Override
+ public String getJavaMethodName(Definition definition, Mode mode) {
+ return "call" + org.jooq.tools.StringUtils.toCamelCase(definition.getOutputName());
+ }
+
+ /**
+ * Override this method to define how your Java classes and Java files should
+ * be named. This example applies no custom setting and uses CamelCase versions
+ * instead
+ */
+ @Override
+ public String getJavaClassName(Definition definition, Mode mode) {
+ return super.getJavaClassName(definition, mode);
+ }
+
+ /**
+ * Override this method to re-define the package names of your generated
+ * artefacts.
+ */
+ @Override
+ public String getJavaPackageName(Definition definition, Mode mode) {
+ return super.getJavaPackageName(definition, mode);
+ }
+
+ /**
+ * Override this method to define how Java members should be named. This is
+ * used for POJOs and method arguments
+ */
+ @Override
+ public String getJavaMemberName(Definition definition, Mode mode) {
+ return definition.getOutputName();
+ }
+}
+
+ + Within the <generator/> element, there are other configuration elements: +
+ +<!-- These properties can be added to the database element: --> +<database> + <!-- Generate java.sql.Timestamp fields for DATE columns. This is + particularly useful for Oracle databases. + Defaults to false --> + <dateAsTimestamp>false</dateAsTimestamp> + + <!-- Generate jOOU data types for your unsigned data types, which are + not natively supported in Java. + Defaults to true --> + <unsignedTypes>true</unsignedTypes> + + <!-- The schema that is used in generated source code. This will be the + production schema. Use this to override your local development + schema name for source code generation. If not specified, this + will be the same as the input-schema. --> + <outputSchema>[your database schema / owner / name]</outputSchema> + + <!-- A configuration element to configure several input and/or output + schemata for jooq-meta, in case you're using jooq-meta in a multi- + schema environment. + This cannot be combined with the above inputSchema / outputSchema --> + <schemata> + <schema> + <inputSchema>...</inputSchema> + <outputSchema>...</outputSchema> + </schema> + [ <schema>...</schema> ... ] + </schemata> + + <!-- A configuration element to configure master data table enum classes --> + <masterDataTables>...</masterDataTables> + + <!-- A configuration element to configure synthetic enum types + This is EXPERIMENTAL functionality. Use at your own risk --> + <enumTypes>...</enumTypes> + + <!-- A configuration element to configure type overrides for generated + artefacts (e.g. in combination with enumTypes) + This is EXPERIMENTAL functionality. Use at your own risk --> + <forcedTypes>...</forcedTypes> +</database>+ +
Also, you can add some optional advanced configuration parameters for the generator:
+ +<!-- These properties can be added to the generate element: --> +<generate> + <!-- Primary key / foreign key relations should be generated and used. + This is a prerequisite for various advanced features. + Defaults to false --> + <relations>false</relations> + + <!-- Generate navigation methods to navigate foreign key relationships + directly from Record classes. This is only relevant if relations + is set to true, too. + Defaults to true --> + <navigationMethods>true</navigationMethods> + + <!-- Generate deprecated code for backwards compatibility + Defaults to true --> + <deprecated>true</deprecated> + + <!-- Generate instance fields in your tables, as opposed to static + fields. This simplifies aliasing. + Defaults to true --> + <instanceFields>true</instanceFields> + + <!-- Generate the javax.annotation.Generated annotation to indicate + jOOQ version used for source code. + Defaults to true --> + <generatedAnnotation>true</generatedAnnotation> + + <!-- Generate POJOs in addition to Record classes for usage of the + ResultQuery.fetchInto(Class) API + Defaults to false --> + <pojos>false</pojos> + + <!-- Annotate POJOs and Records with JPA annotations for increased + compatibility and better integration with JPA/Hibernate, etc + Defaults to false --> + <jpaAnnotations>false</jpaAnnotations> +</generate>+ +
+ Check out the manual's section about + master data + to find out more + about those advanced configuration parameters. +
-2.2. The schema, top-level generated artefact
The schema is the top-level generated object in jOOQ. In many +2.3. The schema, top-level generated artefact
The schema is the top-level generated object in jOOQ. In many RDBMS, the schema coincides with the owner of tables and other objects
The Schema
@@ -1994,7 +2134,7 @@ public void bind(BindContext context) throws DataAccessException;public final java.util.List<org.jooq.Sequence<?>> getSequences(); public final java.util.List<org.jooq.Table<?>> getTables();
-2.3. Tables, views and their corresponding records
+2.4. Tables, views and their corresponding records
The most important generated artefacts are Tables and TableRecords. Every Table has a Record type associated with it that models a single tuple of that entity: Table<R extends Record>. @@ -2065,7 +2205,7 @@ public final java.util.List<org.jooq.Table<?>> getTables(); public List<TBookRecord> fetchTBooks() { // [...] }
-2.4. Procedures and packages
Procedure support is one of the most important reasons why you should consider jOOQ. jOOQ heavily facilitates the use of stored procedures and functions via its source code generation. @@ -2264,7 +2404,7 @@ assertNotNull(author.getLastName());
-2.5. UDT's including ARRAY and ENUM types
+2.6. UDT's including ARRAY and ENUM types
Databases become more powerful when you can structure your data in user defined types. It's time for Java developers to give some credit to that. @@ -2564,7 +2704,7 @@ public class TBookRecord extends UpdatableRecordImpl<TBookRecord> { master data for more details.
-2.6. Sequences
jOOQ also generates convenience artefacts for sequences, where this is supported: DB2, Derby, H2, HSQLDB, Oracle, Postgres, and more.
@@ -3020,6 +3160,8 @@ TableOnConditionStep onKey(ForeignKey<?, ?> key); Condition notIn(Select<?> query); Condition in(Collection<T> values); Condition between(T minValue, T maxValue); + Condition contains(T value); + Condition contains(Field<T> value); Condition equal(T value); Condition equal(Field<T> field); Condition equal(Select<?> query); @@ -3029,6 +3171,8 @@ TableOnConditionStep onKey(ForeignKey<?, ?> key); Condition equalAll(Select<?> query); Condition equalAll(T... array); Condition equalAll(Field<T[]> array); + Condition equalIgnoreCase(String value); + Condition equalIgnoreCase(Field<String> value); Condition notEqual(T value); Condition notEqual(Field<T> field); Condition notEqual(Select<?> query); @@ -4152,15 +4296,18 @@ create.select(LAST_NAME, COUNT1, COUNT2)When a user from My Book World logs in, you want them to access the MY_BOOK_WORLD schema using classes generated from DEV. This can be achieved with the - org.jooq.SchemaMapping - class, that you can equip your Factory + org.jooq.conf.RenderMapping + class, that you can equip your Factory's settings with. Take the following example:
-SchemaMapping mapping = new SchemaMapping();
-mapping.add(DEV, "MY_BOOK_WORLD");
+Settings settings = new Settings()
+ .withRenderMapping(new RenderMapping()
+ .withSchemata(
+ new MappedSchema().withInput("DEV")
+ .withOutput("MY_BOOK_WORLD")));
-// Add the mapping to the factory
-Factory create = new Factory(connection, SQLDialect.ORACLE, mapping);
+// Add the settings to the factory
+Factory create = new Factory(connection, SQLDialect.ORACLE, settings);
// Run queries with the "mapped" factory
create.selectFrom(T_AUTHOR).fetch();
@@ -4174,12 +4321,27 @@ create.selectFrom(T_AUTHOR).fetch();
Your development database may not be restricted to hold only one DEV schema. You may also have a LOG schema and a MASTER schema. Let's say the MASTER schema is shared among all customers, but each customer has - their own LOG schema instance. Then you can enhance your SchemaMapping - like this:
+ their own LOG schema instance. Then you can enhance your RenderMapping + like this (e.g. using an XML configuration file): -SchemaMapping mapping = new SchemaMapping(); -mapping.add(DEV, "MY_BOOK_WORLD"); -mapping.add(LOG, "MY_BOOK_WORLD_LOG");+
<settings xmlns="http://www.jooq.org/xsd/jooq-runtime-2.0.5.xsd"> + <renderMapping> + <schemata> + <schema> + <input>DEV</input> + <output>MY_BOOK_WORLD</output> + </schema> + <schema> + <input>LOG</input> + <output>MY_BOOK_WORLD_LOG</output> + </schema> + </schemata> + </renderMapping> +</settings>+ +
Note, you can load the above XML file like this:
+ +Settings settings = JAXB.unmarshal(new File("jooq-runtime.xml"), Settings.class);
This will map generated classes from DEV to MY_BOOK_WORLD, from LOG to MY_BOOK_WORLD_LOG, but leave the MASTER schema alone. Whenever you @@ -4213,12 +4375,17 @@ SELECT * FROM T_AUTHOR applied to all of your tables. This can be achieved by creating the following mapping:
-SchemaMapping mapping = new SchemaMapping();
-mapping.add(DEV, "MY_BOOK_WORLD");
-mapping.add(T_AUTHOR, "MY_APP__T_AUTHOR");
+Settings settings = new Settings()
+ .withRenderMapping(new RenderMapping()
+ .withSchemata(
+ new MappedSchema().withInput("DEV")
+ .withOutput("MY_BOOK_WORLD")
+ .withTables(
+ new MappedTable().withInput("T_AUTHOR")
+ .withOutput("MY_APP__T_AUTHOR"))));
-// Add the mapping to the factory
-Factory create = new Factory(connection, SQLDialect.ORACLE, mapping);
+// Add the settings to the factory
+Factory create = new Factory(connection, SQLDialect.ORACLE, settings);
// Run queries with the "mapped" factory
create.selectFrom(T_AUTHOR).fetch();
@@ -4247,8 +4414,68 @@ create.selectFrom(T_AUTHOR).fetch();
jooq-codegen configuration
for more details
+ +4.3. Execute listeners and SQL tracing
+ Feel the heart beat of your SQL statements at a very low level using listeners +
+ExecuteListener
++ The jOOQ Factory Settings + let you specify a list of org.jooq.ExecuteListener classes. + The ExecuteListener is essentially an event listener for + Query, Routine, or ResultSet render, prepare, bind, execute, fetch steps. It is a + base type for loggers, debuggers, profilers, data collectors. Advanced ExecuteListeners + can also provide custom implementations of Connection, PreparedStatement and ResultSet + to jOOQ in apropriate methods. For convenience, consider extending + org.jooq.impl.DefaultExecuteListener + instead of implementing this interface. Please read the + ExecuteListener Javadoc + for more details +
+ +jOOQ Console
++ The ExecuteListener API was driven by a feature request by Christopher Deckers, who has + had the courtesy to contribute the jOOQ Console, a sample application interfacing + with jOOQ's ExecuteListeners. Please note that the jOOQ Console is still experimental. + Any feedback is very welcome on + the jooq-user group + +
++ Here are the steps you need to do to run the console +
+// Create a new RemoteDebuggerServer in your application that listens to +// incoming connections on a given port +SERVER = new RemoteDebuggerServer(DEBUGGER_PORT);+ +
+ And configure the org.jooq.debug.DebugListener in the + Factory's settings: +
+ +<settings> + <executeListeners> + <executeListener>org.jooq.debug.DebugListener</executeListener> + </executeListeners> +</settings>+ +
+ Now start your application and the + org.jooq.debug.console.Console, and start profiling! +
+ +
+ + The jOOQ Console also has other modes of execution, which will be documented here + soon. +
-4.3. Adding Oracle hints to queries
+4.4. Adding Oracle hints to queries
Oracle has a powerful syntax to add hints as comments directly in your SQL
How to embed Oracle hints in SELECT
@@ -4267,7 +4494,7 @@ create.selectFrom(T_AUTHOR).fetch(); that clause, the passed string will always be put in between the SELECT [DISTINCT] keywords and the actual projection list-4.4. The Oracle CONNECT BY clause
+4.5. The Oracle CONNECT BY clause
Hierarchical queries are supported by many RDBMS using the WITH clause. Oracle has a very neat and much less verbose syntax for hierarchical queries: CONNECT BY .. STARTS WITH @@ -4318,7 +4545,7 @@ create.select(create.rownum()) |...21 record(s) truncated...
-4.5. The Oracle 11g PIVOT clause
+4.6. The Oracle 11g PIVOT clause
Oracle 11g has formally introduced the very powerful PIVOT clause, which allows to specify a pivot column, expected grouping values for pivoting, as well as a set of aggregate functions @@ -4341,7 +4568,7 @@ create.select(create.rownum()) dialects in the future.
-4.6. Exporting to XML, CSV, JSON, HTML, Text
+4.7. Exporting to XML, CSV, JSON, HTML, Text
Get your data out of the Java world. Stream your data using any of the supported, wide-spread formats
Exporting with jOOQ
@@ -4437,7 +4664,7 @@ String text = create.selectFrom(T_BOOK).fetch().format(); | 2| 1|Animal Farm| +---+---------+-----------+-4.7. Importing data from XML, CSV
+4.8. Importing data from XML, CSV
Use jOOQ to easily merge imported data into your database.
Importing with jOOQ
@@ -4544,7 +4771,7 @@ Query query = error.query();XML
This will be implemented soon...
-4.8. Using JDBC batch operations
+4.9. Using JDBC batch operations
Some JDBC drivers have highly optimised means of executing batch operations. The JDBC interface for those operations is a bit verbose. jOOQ abstracts that by re-using the existing query API's diff --git a/jOOQ-website/manual/ADVANCED/ExecuteListener/index.php b/jOOQ-website/manual/ADVANCED/ExecuteListener/index.php new file mode 100644 index 0000000000..c2c9fa9812 --- /dev/null +++ b/jOOQ-website/manual/ADVANCED/ExecuteListener/index.php @@ -0,0 +1,89 @@ + + +
| The jOOQ User Manual : Advanced topics : Execute listeners and SQL tracing | previous : next | +
ExecuteListener
++ The jOOQ Factory Settings + let you specify a list of org.jooq.ExecuteListener classes. + The ExecuteListener is essentially an event listener for + Query, Routine, or ResultSet render, prepare, bind, execute, fetch steps. It is a + base type for loggers, debuggers, profilers, data collectors. Advanced ExecuteListeners + can also provide custom implementations of Connection, PreparedStatement and ResultSet + to jOOQ in apropriate methods. For convenience, consider extending + org.jooq.impl.DefaultExecuteListener + instead of implementing this interface. Please read the + ExecuteListener Javadoc + for more details +
+ +jOOQ Console
++ The ExecuteListener API was driven by a feature request by Christopher Deckers, who has + had the courtesy to contribute the jOOQ Console, a sample application interfacing + with jOOQ's ExecuteListeners. Please note that the jOOQ Console is still experimental. + Any feedback is very welcome on + the jooq-user group + +
++ Here are the steps you need to do to run the console +
+// Create a new RemoteDebuggerServer in your application that listens to +// incoming connections on a given port +SERVER = new RemoteDebuggerServer(DEBUGGER_PORT);+ +
+ And configure the org.jooq.debug.DebugListener in the + Factory's settings: +
+ +<settings> + <executeListeners> + <executeListener>org.jooq.debug.DebugListener</executeListener> + </executeListeners> +</settings>+ +
+ Now start your application and the + org.jooq.debug.console.Console, and start profiling! +
+ +
+ + The jOOQ Console also has other modes of execution, which will be documented here + soon. +
+| The jOOQ User Manual : Advanced topics : Execute listeners and SQL tracing | previous : next | +
| The jOOQ User Manual : Advanced topics : Adding Oracle hints to queries | previous : next | +The jOOQ User Manual : Advanced topics : Adding Oracle hints to queries | previous : next |
How to embed Oracle hints in SELECT
@@ -39,7 +39,7 @@ function printContent() { SELECT [DISTINCT] keywords and the actual projection list| The jOOQ User Manual : Advanced topics : Adding Oracle hints to queries | previous : next | +The jOOQ User Manual : Advanced topics : Adding Oracle hints to queries | previous : next |
| The jOOQ User Manual : Advanced topics : Mapping generated schemata and tables | previous : next | +The jOOQ User Manual : Advanced topics : Mapping generated schemata and tables | previous : next |
Mapping your DEV schema to a productive environment
@@ -50,15 +50,18 @@ function printContent() {When a user from My Book World logs in, you want them to access the MY_BOOK_WORLD schema using classes generated from DEV. This can be achieved with the - org.jooq.SchemaMapping - class, that you can equip your Factory + org.jooq.conf.RenderMapping + class, that you can equip your Factory's settings with. Take the following example:
-SchemaMapping mapping = new SchemaMapping();
-mapping.add(DEV, "MY_BOOK_WORLD");
+Settings settings = new Settings()
+ .withRenderMapping(new RenderMapping()
+ .withSchemata(
+ new MappedSchema().withInput("DEV")
+ .withOutput("MY_BOOK_WORLD")));
-// Add the mapping to the factory
-Factory create = new Factory(connection, SQLDialect.ORACLE, mapping);
+// Add the settings to the factory
+Factory create = new Factory(connection, SQLDialect.ORACLE, settings);
// Run queries with the "mapped" factory
create.selectFrom(T_AUTHOR).fetch();
@@ -72,12 +75,27 @@ create.selectFrom(T_AUTHOR).fetch();
Your development database may not be restricted to hold only one DEV schema. You may also have a LOG schema and a MASTER schema. Let's say the MASTER schema is shared among all customers, but each customer has - their own LOG schema instance. Then you can enhance your SchemaMapping - like this:
+ their own LOG schema instance. Then you can enhance your RenderMapping + like this (e.g. using an XML configuration file): -SchemaMapping mapping = new SchemaMapping(); -mapping.add(DEV, "MY_BOOK_WORLD"); -mapping.add(LOG, "MY_BOOK_WORLD_LOG");+
<settings xmlns="http://www.jooq.org/xsd/jooq-runtime-2.0.5.xsd"> + <renderMapping> + <schemata> + <schema> + <input>DEV</input> + <output>MY_BOOK_WORLD</output> + </schema> + <schema> + <input>LOG</input> + <output>MY_BOOK_WORLD_LOG</output> + </schema> + </schemata> + </renderMapping> +</settings>+ +
Note, you can load the above XML file like this:
+ +Settings settings = JAXB.unmarshal(new File("jooq-runtime.xml"), Settings.class);
This will map generated classes from DEV to MY_BOOK_WORLD, from LOG to MY_BOOK_WORLD_LOG, but leave the MASTER schema alone. Whenever you @@ -111,12 +129,17 @@ SELECT * FROM T_AUTHOR applied to all of your tables. This can be achieved by creating the following mapping:
-SchemaMapping mapping = new SchemaMapping();
-mapping.add(DEV, "MY_BOOK_WORLD");
-mapping.add(T_AUTHOR, "MY_APP__T_AUTHOR");
+Settings settings = new Settings()
+ .withRenderMapping(new RenderMapping()
+ .withSchemata(
+ new MappedSchema().withInput("DEV")
+ .withOutput("MY_BOOK_WORLD")
+ .withTables(
+ new MappedTable().withInput("T_AUTHOR")
+ .withOutput("MY_APP__T_AUTHOR"))));
-// Add the mapping to the factory
-Factory create = new Factory(connection, SQLDialect.ORACLE, mapping);
+// Add the settings to the factory
+Factory create = new Factory(connection, SQLDialect.ORACLE, settings);
// Run queries with the "mapped" factory
create.selectFrom(T_AUTHOR).fetch();
@@ -147,7 +170,7 @@ create.selectFrom(T_AUTHOR).fetch();
| The jOOQ User Manual : Advanced topics : Mapping generated schemata and tables | previous : next | +The jOOQ User Manual : Advanced topics : Mapping generated schemata and tables | previous : next |
If you are planning on using several RDBMS (= SQLDialects) or several distinct JDBC Connections in your software, this will mean that you have to create a new Factory every time.
+Factory settings
++ The jOOQ Factory allows for some optional configuration elements to be used by advanced users. + The Settings class is a JAXB-annotated + type. In future releases of jOOQ, these settings can be loaded from an XML file automatically. + Subsequent sections of the manual contain some more in-depth explanations about these settings: +
+-
+
+
- + +Runtime schema and table mapping + + + +
- + +Execute listeners and SQL tracing + + + +
+ Please refer to the jOOQ runtime configuration XSD for more details:
+
+http://www.jooq.org/xsd/jooq-runtime-2.0.5.xsd
+
+
Factory subclasses
There are a couple of subclasses for the general Factory. Each SQL diff --git a/jOOQ-website/manual/JOOQ/ResultQuery/index.php b/jOOQ-website/manual/JOOQ/ResultQuery/index.php index 02bc76df44..0e8a63ed49 100644 --- a/jOOQ-website/manual/JOOQ/ResultQuery/index.php +++ b/jOOQ-website/manual/JOOQ/ResultQuery/index.php @@ -92,6 +92,9 @@ Object[] fetchArray(String fieldName); // Fetch a Cursor for lazy iteration Cursor<R> fetchLazy(); +// Or a JDBC ResultSet, if you prefer that +ResultSet fetchResultSet(); + // Fetch data asynchronously and let client code // decide, when the data must be available. // This makes use of the java.util.concurrent API, diff --git a/jOOQ-website/manual/META/AdvancedConfiguration/index.php b/jOOQ-website/manual/META/AdvancedConfiguration/index.php new file mode 100644 index 0000000000..7d7a68d6b9 --- /dev/null +++ b/jOOQ-website/manual/META/AdvancedConfiguration/index.php @@ -0,0 +1,231 @@ + + +
| The jOOQ User Manual : Meta model code generation : Advanced configuration of the generator | previous : next | +
Code generation
++ In the previous section + we have seen how jOOQ's source code generator is configured and + run within a few steps. In this chapter we'll treat some advanced + settings +
+ +<!-- These properties can be added directly to the generator element: --> +<generator> + <!-- The default code generator. You can override this one, to generate your own code style + Defaults to org.jooq.util.DefaultGenerator --> + <name>org.jooq.util.DefaultGenerator</name> + + <!-- The naming strategy used for class and field names. + You may override this with your custom naming strategy. Some examples follow + Defaults to org.jooq.util.DefaultGeneratorStrategy --> + <strategy> + <name>org.jooq.util.DefaultGeneratorStrategy</name> + </strategy> +</generator>+ +
+ The following example shows how you can override the + DefaultGeneratorStrategy to render table and column names the way + they are defined in the database, rather than switching them to + camel case: +
+ +/**
+ * It is recommended that you extend the DefaultGeneratorStrategy. Most of the
+ * GeneratorStrategy API is already declared final. You only need to override any
+ * of the following methods, for whatever generation behaviour you'd like to achieve
+ *
+ * Beware that most methods also receive a "Mode" object, to tell you whether a
+ * TableDefinition is being rendered as a Table, Record, POJO, etc. Depending on
+ * that information, you can add a suffix only for TableRecords, not for Tables
+ */
+public class AsInDatabaseStrategy extends DefaultGeneratorStrategy {
+
+ /**
+ * Override this to specifiy what identifiers in Java should look like.
+ * This will just take the identifier as defined in the database.
+ */
+ @Override
+ public String getJavaIdentifier(Definition definition) {
+ return definition.getOutputName();
+ }
+
+ /**
+ * Override these to specify what a setter in Java should look like. Setters
+ * are used in TableRecords, UDTRecords, and POJOs. This example will name
+ * setters "set[NAME_IN_DATABASE]"
+ */
+ @Override
+ public String getJavaSetterName(Definition definition, Mode mode) {
+ return "set" + definition.getOutputName();
+ }
+
+ /**
+ * Just like setters...
+ */
+ @Override
+ public String getJavaGetterName(Definition definition, Mode mode) {
+ return "get" + definition.getOutputName();
+ }
+
+ /**
+ * Override this method to define what a Java method generated from a database
+ * Definition should look like. This is used mostly for convenience methods
+ * when calling stored procedures and functions. This example shows how to
+ * set a prefix to a CamelCase version of your procedure
+ */
+ @Override
+ public String getJavaMethodName(Definition definition, Mode mode) {
+ return "call" + org.jooq.tools.StringUtils.toCamelCase(definition.getOutputName());
+ }
+
+ /**
+ * Override this method to define how your Java classes and Java files should
+ * be named. This example applies no custom setting and uses CamelCase versions
+ * instead
+ */
+ @Override
+ public String getJavaClassName(Definition definition, Mode mode) {
+ return super.getJavaClassName(definition, mode);
+ }
+
+ /**
+ * Override this method to re-define the package names of your generated
+ * artefacts.
+ */
+ @Override
+ public String getJavaPackageName(Definition definition, Mode mode) {
+ return super.getJavaPackageName(definition, mode);
+ }
+
+ /**
+ * Override this method to define how Java members should be named. This is
+ * used for POJOs and method arguments
+ */
+ @Override
+ public String getJavaMemberName(Definition definition, Mode mode) {
+ return definition.getOutputName();
+ }
+}
+
+ + Within the <generator/> element, there are other configuration elements: +
+ +<!-- These properties can be added to the database element: --> +<database> + <!-- Generate java.sql.Timestamp fields for DATE columns. This is + particularly useful for Oracle databases. + Defaults to false --> + <dateAsTimestamp>false</dateAsTimestamp> + + <!-- Generate jOOU data types for your unsigned data types, which are + not natively supported in Java. + Defaults to true --> + <unsignedTypes>true</unsignedTypes> + + <!-- The schema that is used in generated source code. This will be the + production schema. Use this to override your local development + schema name for source code generation. If not specified, this + will be the same as the input-schema. --> + <outputSchema>[your database schema / owner / name]</outputSchema> + + <!-- A configuration element to configure several input and/or output + schemata for jooq-meta, in case you're using jooq-meta in a multi- + schema environment. + This cannot be combined with the above inputSchema / outputSchema --> + <schemata> + <schema> + <inputSchema>...</inputSchema> + <outputSchema>...</outputSchema> + </schema> + [ <schema>...</schema> ... ] + </schemata> + + <!-- A configuration element to configure master data table enum classes --> + <masterDataTables>...</masterDataTables> + + <!-- A configuration element to configure synthetic enum types + This is EXPERIMENTAL functionality. Use at your own risk --> + <enumTypes>...</enumTypes> + + <!-- A configuration element to configure type overrides for generated + artefacts (e.g. in combination with enumTypes) + This is EXPERIMENTAL functionality. Use at your own risk --> + <forcedTypes>...</forcedTypes> +</database>+ +
Also, you can add some optional advanced configuration parameters for the generator:
+ +<!-- These properties can be added to the generate element: --> +<generate> + <!-- Primary key / foreign key relations should be generated and used. + This is a prerequisite for various advanced features. + Defaults to false --> + <relations>false</relations> + + <!-- Generate navigation methods to navigate foreign key relationships + directly from Record classes. This is only relevant if relations + is set to true, too. + Defaults to true --> + <navigationMethods>true</navigationMethods> + + <!-- Generate deprecated code for backwards compatibility + Defaults to true --> + <deprecated>true</deprecated> + + <!-- Generate instance fields in your tables, as opposed to static + fields. This simplifies aliasing. + Defaults to true --> + <instanceFields>true</instanceFields> + + <!-- Generate the javax.annotation.Generated annotation to indicate + jOOQ version used for source code. + Defaults to true --> + <generatedAnnotation>true</generatedAnnotation> + + <!-- Generate POJOs in addition to Record classes for usage of the + ResultQuery.fetchInto(Class) API + Defaults to false --> + <pojos>false</pojos> + + <!-- Annotate POJOs and Records with JPA annotations for increased + compatibility and better integration with JPA/Hibernate, etc + Defaults to false --> + <jpaAnnotations>false</jpaAnnotations> +</generate>+ +
+ Check out the manual's section about + master data + to find out more + about those advanced configuration parameters. +
+| The jOOQ User Manual : Meta model code generation : Advanced configuration of the generator | previous : next | +
The deliverables
@@ -85,17 +85,6 @@ function printContent() { </jdbc> <generator> - <!-- The default code generator. You can override this one, to generate your own code style - Defaults to org.jooq.util.DefaultGenerator --> - <name>org.jooq.util.DefaultGenerator</name> - - <!-- The naming strategy used for class and field names. - You may override this with your custom naming strategy. - Defaults to org.jooq.util.DefaultGeneratorStrategy --> - <strategy> - <name>org.jooq.util.DefaultGeneratorStrategy</name> - </strategy> - <database> <!-- The database dialect from jooq-meta. Available dialects are named org.util.[database].[database]Database. Known values are: @@ -151,97 +140,10 @@ function printContent() { </generator> </configuration> -And you can add some optional advanced configuration parameters for the database:
- -<!-- These properties can be added to the database element: --> -<database> - <!-- Generate java.sql.Timestamp fields for DATE columns. This is - particularly useful for Oracle databases. - Defaults to false --> - <dateAsTimestamp>false</dateAsTimestamp> - - <!-- Generate jOOU data types for your unsigned data types, which are - not natively supported in Java. - Defaults to true --> - <unsignedTypes>true</unsignedTypes> - - <!-- The schema that is used in generated source code. This will be the - production schema. Use this to override your local development - schema name for source code generation. If not specified, this - will be the same as the input-schema. --> - <outputSchema>[your database schema / owner / name]</outputSchema> - - <!-- A configuration element to configure several input and/or output - schemata for jooq-meta, in case you're using jooq-meta in a multi- - schema environment. - This cannot be combined with the above inputSchema / outputSchema --> - <schemata> - <schema> - <inputSchema>...</inputSchema> - <outputSchema>...</outputSchema> - </schema> - [ <schema>...</schema> ... ] - </schemata> - - <!-- A configuration element to configure master data table enum classes --> - <masterDataTables>...</masterDataTables> - - <!-- A configuration element to configure synthetic enum types - This is EXPERIMENTAL functionality. Use at your own risk --> - <enumTypes>...</enumTypes> - - <!-- A configuration element to configure type overrides for generated - artefacts (e.g. in combination with enumTypes) - This is EXPERIMENTAL functionality. Use at your own risk --> - <forcedTypes>...</forcedTypes> -</database>- -
Also, you can add some optional advanced configuration parameters for the generator:
- -<!-- These properties can be added to the generate element: --> -<generate> - <!-- Primary key / foreign key relations should be generated and used. - This is a prerequisite for various advanced features. - Defaults to false --> - <relations>false</relations> - - <!-- Generate navigation methods to navigate foreign key relationships - directly from Record classes. This is only relevant if relations - is set to true, too. - Defaults to true --> - <navigationMethods>true</navigationMethods> - - <!-- Generate deprecated code for backwards compatibility - Defaults to true --> - <deprecated>true</deprecated> - - <!-- Generate instance fields in your tables, as opposed to static - fields. This simplifies aliasing. - Defaults to true --> - <instanceFields>true</instanceFields> - - <!-- Generate the javax.annotation.Generated annotation to indicate - jOOQ version used for source code. - Defaults to true --> - <generatedAnnotation>true</generatedAnnotation> - - <!-- Generate POJOs in addition to Record classes for usage of the - ResultQuery.fetchInto(Class) API - Defaults to false --> - <pojos>false</pojos> - - <!-- Annotate POJOs and Records with JPA annotations for increased - compatibility and better integration with JPA/Hibernate, etc - Defaults to false --> - <jpaAnnotations>false</jpaAnnotations> -</generate>- -
Check out the manual's section about - master data - to find out more - about those advanced configuration parameters.
- -Also, check out the official XSD file at +
+ There are also lots of advanced configuration parameters, which will be + treated in the manual's next section + Note, you can find the official XSD file at http://www.jooq.org/xsd/jooq-codegen-2.0.4.xsd for a formal specification
@@ -424,7 +326,7 @@ function printContent() { can execute SQL statements with your generated classes.The Schema
@@ -55,7 +55,7 @@ function printContent() { public final java.util.List<org.jooq.Table<?>> getTables();If you are planning on using several RDBMS (= SQLDialects) or several distinct JDBC Connections in your software, this will mean that you have to create a new Factory every time.
+Factory settings
+
+ The jOOQ Factory allows for some optional configuration elements to be used by advanced users.
+ The
-
+
-
+
+
+ -
+
+
+
+ Please refer to the jOOQ runtime configuration XSD for more details:
+ http://www.jooq.org/xsd/jooq-runtime-2.0.5.xsd
+
Factory subclasses
There are a couple of subclasses for the general Factory. Each SQL
@@ -1018,6 +1036,9 @@ Object[] fetchArray(String fieldName);
// Fetch a Cursor for lazy iteration
Cursor Also, you can add some optional advanced configuration parameters for the generator: Check out the manual's section about
- Also, check out the official XSD file at
+
+ There are also lots of advanced configuration parameters, which will be
+ treated in the
+ In the
+ The following example shows how you can override the
+ DefaultGeneratorStrategy to render table and column names the way
+ they are defined in the database, rather than switching them to
+ camel case:
+
+ Within the <generator/> element, there are other configuration elements:
+ Also, you can add some optional advanced configuration parameters for the generator:
+ Check out the manual's section about
+ When a user from My Book World logs in, you want them to access the
MY_BOOK_WORLD schema using classes generated from DEV. This can be
achieved with the
- Your development database may not be restricted to hold only one DEV
schema. You may also have a LOG schema and a MASTER schema. Let's say
the MASTER schema is shared among all customers, but each customer has
- their own LOG schema instance. Then you can enhance your SchemaMapping
- like this: Code generation
+
Note, you can load the above XML file like this:
+ +This will map generated classes from DEV to MY_BOOK_WORLD, from LOG to MY_BOOK_WORLD_LOG, but leave the MASTER schema alone. Whenever you @@ -3997,12 +4150,17 @@ SELECT * FROM T_AUTHOR applied to all of your tables. This can be achieved by creating the following mapping:
-ExecuteListener
+
+ The
jOOQ Console
++ The ExecuteListener API was driven by a feature request by Christopher Deckers, who has + had the courtesy to contribute the jOOQ Console, a sample application interfacing + with jOOQ's ExecuteListeners. Please note that the jOOQ Console is still experimental. + Any feedback is very welcome on + the jooq-user group +
++ Here are the steps you need to do to run the console +
+
+ And configure the
+ Now start your application and the
+
+ + The jOOQ Console also has other modes of execution, which will be documented here + soon. +
+