Configuration.
*
@@ -154,13 +126,52 @@ public interface Configuration extends Serializable {
*/
Object data(Object key, Object value);
+ // -------------------------------------------------------------------------
+ // Getters
+ // -------------------------------------------------------------------------
+
/**
- * Get the configured ExecuteListenerProvider from this
+ * Get this configuration's underlying connection provider.
+ */
+ ConnectionProvider connectionProvider();
+
+ /**
+ * Get this configuration's underlying record mapper provider.
+ */
+ RecordMapperProvider recordMapperProvider();
+
+ /**
+ * Get the configured RecordListenerProviders from this
+ * configuration.
+ *
+ * This method allows for retrieving the configured
+ * RecordListenerProvider from this configuration. The
+ * providers will provide jOOQ with {@link RecordListener} instances. These
+ * instances receive record manipulation notification events every time jOOQ
+ * executes queries. jOOQ makes no assumptions about the internal state of
+ * these listeners, i.e. listener instances may
+ *
Configuration's lifecycle (i.e. that of a
+ * JDBC Connection, or that of a transaction)RecordContext (i.e. that of a
+ * single record manipulation)ExecuteListenerProviders from this
* configuration.
*
* This method allows for retrieving the configured
* ExecuteListenerProvider from this configuration. The
- * provider will provide jOOQ with {@link ExecuteListener} instances. These
+ * providers will provide jOOQ with {@link ExecuteListener} instances. These
* instances receive execution lifecycle notification events every time jOOQ
* executes queries. jOOQ makes no assumptions about the internal state of
* these listeners, i.e. listener instances may
@@ -183,22 +194,28 @@ public interface Configuration extends Serializable {
*/
ExecuteListenerProvider[] executeListenerProviders();
+ /**
+ * Retrieve the configured schema mapping.
+ *
+ * @deprecated - 2.0.5 - Use {@link #settings()} instead
+ */
+ @Deprecated
+ SchemaMapping schemaMapping();
+
+ /**
+ * Retrieve the configured dialect.
+ */
+ SQLDialect dialect();
+
+ /**
+ * Retrieve the runtime configuration settings.
+ */
+ Settings settings();
+
// -------------------------------------------------------------------------
// Setters
// -------------------------------------------------------------------------
- /**
- * Change this configuration to hold a new dialect.
- *
- * This method is not thread-safe and should not be used in globally
- * available Configuration objects.
- *
- * @param newDialect The new dialect to be contained in the changed
- * configuration.
- * @return The changed configuration.
- */
- Configuration set(SQLDialect newDialect);
-
/**
* Change this configuration to hold a new connection provider.
*
@@ -224,16 +241,16 @@ public interface Configuration extends Serializable { Configuration set(RecordMapperProvider newRecordMapperProvider); /** - * Change this configuration to hold a new settings. + * Change this configuration to hold a new record listener providers. *
* This method is not thread-safe and should not be used in globally
* available Configuration objects.
*
- * @param newSettings The new settings to be contained in the changed
- * configuration.
+ * @param newRecordListenerProviders The new record listener providers to
+ * be contained in the changed configuration.
* @return The changed configuration.
*/
- Configuration set(Settings newSettings);
+ Configuration set(RecordListenerProvider... newRecordListenerProviders);
/**
* Change this configuration to hold a new execute listener providers.
@@ -247,6 +264,30 @@ public interface Configuration extends Serializable {
*/
Configuration set(ExecuteListenerProvider... newExecuteListenerProviders);
+ /**
+ * Change this configuration to hold a new dialect.
+ *
+ * This method is not thread-safe and should not be used in globally
+ * available Configuration objects.
+ *
+ * @param newDialect The new dialect to be contained in the changed
+ * configuration.
+ * @return The changed configuration.
+ */
+ Configuration set(SQLDialect newDialect);
+
+ /**
+ * Change this configuration to hold a new settings.
+ *
+ * This method is not thread-safe and should not be used in globally
+ * available Configuration objects.
+ *
+ * @param newSettings The new settings to be contained in the changed
+ * configuration.
+ * @return The changed configuration.
+ */
+ Configuration set(Settings newSettings);
+
// -------------------------------------------------------------------------
// Derivation methods
// -------------------------------------------------------------------------
@@ -259,15 +300,6 @@ public interface Configuration extends Serializable {
*/
Configuration derive();
- /**
- * Create a derived configuration from this one, with a new dialect.
- *
- * @param newDialect The new dialect to be contained in the derived
- * configuration.
- * @return The derived configuration.
- */
- Configuration derive(SQLDialect newDialect);
-
/**
* Create a derived configuration from this one, with a new connection
* provider.
@@ -289,16 +321,17 @@ public interface Configuration extends Serializable {
Configuration derive(RecordMapperProvider newRecordMapperProvider);
/**
- * Create a derived configuration from this one, with new settings.
+ * Create a derived configuration from this one, with new record listener
+ * providers.
*
- * @param newSettings The new settings to be contained in the derived
- * configuration.
+ * @param newRecordListenerProviders The new record listener providers to
+ * be contained in the derived configuration.
* @return The derived configuration.
*/
- Configuration derive(Settings newSettings);
+ Configuration derive(RecordListenerProvider... newRecordListenerProviders);
/**
- * Create a derived configuration from this one, with a new execute listener
+ * Create a derived configuration from this one, with new execute listener
* providers.
*
* @param newExecuteListenerProviders The new execute listener providers to
@@ -307,4 +340,21 @@ public interface Configuration extends Serializable {
*/
Configuration derive(ExecuteListenerProvider... newExecuteListenerProviders);
+ /**
+ * Create a derived configuration from this one, with a new dialect.
+ *
+ * @param newDialect The new dialect to be contained in the derived
+ * configuration.
+ * @return The derived configuration.
+ */
+ Configuration derive(SQLDialect newDialect);
+
+ /**
+ * Create a derived configuration from this one, with new settings.
+ *
+ * @param newSettings The new settings to be contained in the derived
+ * configuration.
+ * @return The derived configuration.
+ */
+ Configuration derive(Settings newSettings);
}
diff --git a/jOOQ/src/main/java/org/jooq/RecordContext.java b/jOOQ/src/main/java/org/jooq/RecordContext.java
new file mode 100644
index 0000000000..3c52d0885f
--- /dev/null
+++ b/jOOQ/src/main/java/org/jooq/RecordContext.java
@@ -0,0 +1,147 @@
+/**
+ * Copyright (c) 2009-2013, Lukas Eder, lukas.eder@gmail.com
+ * All rights reserved.
+ *
+ * This software is licensed to you under the Apache License, Version 2.0
+ * (the "License"); You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * . Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ *
+ * . Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ *
+ * . Neither the name "jOOQ" nor the names of its contributors may be
+ * used to endorse or promote products derived from this software without
+ * specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+package org.jooq;
+
+import java.util.Map;
+
+/**
+ * A context object for {@link UpdatableRecord} manipulation passed to
+ * registered {@link RecordListener}'s.
+ *
+ * @author Lukas Eder
+ */
+public interface RecordContext {
+
+ /**
+ * Get all custom data from this RecordContext.
+ *
+ * This is custom data that was previously set to the record context using + * {@link #data(Object, Object)}. Use custom data if you want to pass data + * between events received by a {@link RecordListener}. + *
+ * Unlike {@link Configuration#data()}, these data's lifecycle only matches
+ * that of a single record manipulation.
+ *
+ * @return The custom data. This is never
+ * This is custom data that was previously set to the record context using
+ * {@link #data(Object, Object)}. Use custom data if you want to pass data
+ * between events received by an {@link RecordListener}.
+ *
+ * Unlike {@link Configuration#data()}, these data's lifecycle only matches
+ * that of a single query execution.
+ *
+ * @param key A key to identify the custom data
+ * @return The custom data or
+ * This is custom data that was previously set to the record context using
+ * {@link #data(Object, Object)}. Use custom data if you want to pass data
+ * between events received by an {@link RecordListener}.
+ *
+ * Unlike {@link Configuration#data()}, these data's lifecycle only matches
+ * that of a single query execution.
+ *
+ * @param key A key to identify the custom data
+ * @param value The custom data or
+ * Unlike {@link ExecuteContext#type()}, this can only result in any of
+ * these:
+ *
+ * If a single
+ * Users may want to centrally inject custom behaviour when manipulating their
+ * {@link UpdatableRecord} objects, performing CRUD. This service provider
+ * allows to hook in callback method implementations for before or after any of
+ * these methods:
+ *
+ * Implementations are allowed to modify {@link RecordContext#record()}
+ * prior to storing. Note that modifying the record's primary key value may
+ * influence whether storing results in an
+ * Implementations are allowed to modify {@link RecordContext#record()}
+ * after storing. Note that modifying the record's primary key value may
+ * influence whether storing results in an
+ * Implementations are allowed to modify {@link RecordContext#record()}
+ * prior to inserting.
+ *
+ * @see UpdatableRecord#insert()
+ */
+ void insertStart(RecordContext ctx);
+
+ /**
+ * Called after inserting an
+ * Implementations are allowed to modify {@link RecordContext#record()}
+ * after inserting.
+ *
+ * @see UpdatableRecord#insert()
+ */
+ void insertEnd(RecordContext ctx);
+
+ /**
+ * Called before updating an
+ * Implementations are allowed to modify {@link RecordContext#record()}
+ * prior to updating.
+ *
+ * @see UpdatableRecord#update()
+ */
+ void updateStart(RecordContext ctx);
+
+ /**
+ * Called after updating an
+ * Implementations are allowed to modify {@link RecordContext#record()}
+ * after updating.
+ *
+ * @see UpdatableRecord#update()
+ */
+ void updateEnd(RecordContext ctx);
+
+ /**
+ * Called before deleting an
+ * Implementations are allowed to modify {@link RecordContext#record()}
+ * prior to deleting.
+ *
+ * @see UpdatableRecord#delete()
+ */
+ void deleteStart(RecordContext ctx);
+
+ /**
+ * Called after deleting an
+ * Implementations are allowed to modify {@link RecordContext#record()}
+ * after deleting.
+ *
+ * @see UpdatableRecord#delete()
+ */
+ void deleteEnd(RecordContext ctx);
+
+ /**
+ * Called before refreshing an
+ * Implementations are allowed to modify {@link RecordContext#record()}
+ * prior to refreshing.
+ *
+ * @see UpdatableRecord#refresh()
+ */
+ void refreshStart(RecordContext ctx);
+
+ /**
+ * Called after refreshing an
+ * Implementations are allowed to modify {@link RecordContext#record()}
+ * after refreshing.
+ *
+ * @see UpdatableRecord#refresh()
+ */
+ void refreshEnd(RecordContext ctx);
+}
diff --git a/jOOQ/src/main/java/org/jooq/RecordListenerProvider.java b/jOOQ/src/main/java/org/jooq/RecordListenerProvider.java
new file mode 100644
index 0000000000..c290fbebfb
--- /dev/null
+++ b/jOOQ/src/main/java/org/jooq/RecordListenerProvider.java
@@ -0,0 +1,72 @@
+/**
+ * Copyright (c) 2009-2013, Lukas Eder, lukas.eder@gmail.com
+ * All rights reserved.
+ *
+ * This software is licensed to you under the Apache License, Version 2.0
+ * (the "License"); You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * . Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ *
+ * . Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ *
+ * . Neither the name "jOOQ" nor the names of its contributors may be
+ * used to endorse or promote products derived from this software without
+ * specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+package org.jooq;
+
+import org.jooq.impl.DefaultRecordListenerProvider;
+
+/**
+ * A provider for {@link RecordListener} instances.
+ *
+ * In order to facilitate the lifecycle management of
+ *
+ * Implementations are free to choose whether this method returns new
+ * instances at every call or whether the same instance is returned
+ * repetitively.
+ *
+ * A
+ * This implementation just wraps an instance of {@link RecordListener}, always
+ * providing the same.
+ *
+ * @author Lukas Eder
+ */
+public class DefaultRecordListenerProvider implements RecordListenerProvider, Serializable {
+
+ /**
+ * Generated UID.
+ */
+ private static final long serialVersionUID = -2122007794302549679L;
+
+ /**
+ * The delegate list.
+ */
+ private final RecordListener listener;
+
+ /**
+ * Convenience method to construct an array of
+ * null
+ * @see RecordListener
+ */
+ MapRecordContext.
+ * null if no such data is contained
+ * in this RecordContext
+ * @see RecordListener
+ */
+ Object data(Object key);
+
+ /**
+ * Set some custom data to this RecordContext.
+ * null to unset the custom
+ * data
+ * @return The previously set custom data or null if no data
+ * was previously set for the given key
+ * @see RecordListener
+ */
+ Object data(Object key, Object value);
+
+ /**
+ * The configuration wrapped by this context.
+ */
+ Configuration configuration();
+
+ /**
+ * The type of database interaction that is being executed.
+ *
+ *
+ *
+ * @see ExecuteType
+ */
+ ExecuteType type();
+
+ /**
+ * The UpdatableRecord that is being manipulated.
+ *
+ * @return The UpdatableRecord being manipulated. This is never
+ * null
+ */
+ UpdatableRecord record();
+
+ /**
+ * The UpdatableRecord(s) that are being manipulated in batch
+ * mode.
+ * UpdatableRecord is being manipulated in
+ * non-batch mode, this will return an array of length 1,
+ * containing that Record.
+ *
+ * @return The UpdatableRecord(s) being manipulated. This is
+ * never null
+ */
+ UpdatableRecord[] batchRecords();
+}
diff --git a/jOOQ/src/main/java/org/jooq/RecordListener.java b/jOOQ/src/main/java/org/jooq/RecordListener.java
new file mode 100644
index 0000000000..ed2e849463
--- /dev/null
+++ b/jOOQ/src/main/java/org/jooq/RecordListener.java
@@ -0,0 +1,160 @@
+/**
+ * Copyright (c) 2009-2013, Lukas Eder, lukas.eder@gmail.com
+ * All rights reserved.
+ *
+ * This software is licensed to you under the Apache License, Version 2.0
+ * (the "License"); You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * . Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ *
+ * . Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ *
+ * . Neither the name "jOOQ" nor the names of its contributors may be
+ * used to endorse or promote products derived from this software without
+ * specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+package org.jooq;
+
+/**
+ * A listener for manipulation events on {@link UpdatableRecord}s.
+ *
+ *
+ *
+ * @author Lukas Eder
+ */
+public interface RecordListener {
+
+ /**
+ * Called before storing an UpdatableRecord.
+ * INSERT or
+ * UPDATE statement.
+ *
+ * @see UpdatableRecord#store()
+ */
+ void storeStart(RecordContext ctx);
+
+ /**
+ * Called after storing an UpdatableRecord.
+ * INSERT or
+ * UPDATE statement.
+ *
+ * @see UpdatableRecord#store()
+ */
+ void storeEnd(RecordContext ctx);
+
+ /**
+ * Called before inserting an UpdatableRecord.
+ * UpdatableRecord.
+ * UpdatableRecord.
+ * UpdatableRecord.
+ * UpdatableRecord.
+ * UpdatableRecord.
+ * UpdatableRecord.
+ * UpdatableRecord.
+ * RecordListener instances that are provided to a jOOQ
+ * {@link Configuration}, clients can implement this API. To jOOQ, it is thus
+ * irrelevant, if execute listeners are stateful or stateless, local to a
+ * single record or record manipulation, or global to an application.
+ *
+ * @author Lukas Eder
+ * @see RecordListener
+ * @see Configuration
+ */
+public interface RecordListenerProvider {
+
+ /**
+ * Provide a RecordListener instance.
+ * RecordListener shall be provided exactly once per
+ * UpdatableRecord manipulation, i.e. per
+ * RecordContext.
+ *
+ * @return An RecordListener instance.
+ * @see RecordListener
+ * @see RecordContext
+ * @see DefaultRecordListenerProvider
+ */
+ RecordListener provide();
+}
diff --git a/jOOQ/src/main/java/org/jooq/impl/DefaultConfiguration.java b/jOOQ/src/main/java/org/jooq/impl/DefaultConfiguration.java
index d985340d4d..fc8f2291ae 100644
--- a/jOOQ/src/main/java/org/jooq/impl/DefaultConfiguration.java
+++ b/jOOQ/src/main/java/org/jooq/impl/DefaultConfiguration.java
@@ -51,6 +51,7 @@ import org.jooq.Configuration;
import org.jooq.ConnectionProvider;
import org.jooq.DSLContext;
import org.jooq.ExecuteListenerProvider;
+import org.jooq.RecordListenerProvider;
import org.jooq.RecordMapperProvider;
import org.jooq.SQLDialect;
import org.jooq.SchemaMapping;
@@ -81,7 +82,8 @@ public class DefaultConfiguration implements Configuration {
// Non-serializable Configuration objects
private transient ConnectionProvider connectionProvider;
private transient RecordMapperProvider recordMapperProvider;
- private transient ExecuteListenerProvider[] listenerProviders;
+ private transient RecordListenerProvider[] recordListenerProviders;
+ private transient ExecuteListenerProvider[] executeListenerProviders;
// Derived objects
private org.jooq.SchemaMapping mapping;
@@ -101,6 +103,7 @@ public class DefaultConfiguration implements Configuration {
this(
new NoConnectionProvider(),
new DefaultRecordMapperProvider(),
+ new RecordListenerProvider[0],
new ExecuteListenerProvider[0],
SQL99,
SettingsTools.defaultSettings(),
@@ -119,6 +122,7 @@ public class DefaultConfiguration implements Configuration {
this(
configuration.connectionProvider(),
configuration.recordMapperProvider(),
+ configuration.recordListenerProviders(),
configuration.executeListenerProviders(),
configuration.dialect(),
configuration.settings(),
@@ -137,14 +141,16 @@ public class DefaultConfiguration implements Configuration {
DefaultConfiguration(
ConnectionProvider connectionProvider,
RecordMapperProvider recordMapperProvider,
- ExecuteListenerProvider[] listenerProviders,
+ RecordListenerProvider[] recordListenerProviders,
+ ExecuteListenerProvider[] executeListenerProviders,
SQLDialect dialect,
Settings settings,
MapDefaultRecordListenerProvider from an array of
+ * RecordListener instances.
+ */
+ public static RecordListenerProvider[] providers(RecordListener... listeners) {
+ RecordListenerProvider[] result = new RecordListenerProvider[listeners.length];
+
+ for (int i = 0; i < listeners.length; i++) {
+ result[i] = new DefaultRecordListenerProvider(listeners[i]);
+ }
+
+ return result;
+ }
+
+ /**
+ * Create a new provider instance from an argument listener.
+ *
+ * @param listener The argument listener.
+ */
+ public DefaultRecordListenerProvider(RecordListener listener) {
+ this.listener = listener;
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ @Override
+ public final RecordListener provide() {
+ return listener;
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ @Override
+ public String toString() {
+ return listener.toString();
+ }
+}