From 82d723524964154dfa85d5f3db2b1f784b18e380 Mon Sep 17 00:00:00 2001 From: dsyer Date: Wed, 12 Dec 2007 23:14:34 +0000 Subject: [PATCH] Tweak Javadocs --- .../io/driving/DrivingQueryInputSource.java | 119 ++++++++++-------- 1 file changed, 66 insertions(+), 53 deletions(-) diff --git a/spring-batch-infrastructure/src/main/java/org/springframework/batch/io/driving/DrivingQueryInputSource.java b/spring-batch-infrastructure/src/main/java/org/springframework/batch/io/driving/DrivingQueryInputSource.java index 30a27130d..5701c4819 100644 --- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/io/driving/DrivingQueryInputSource.java +++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/io/driving/DrivingQueryInputSource.java @@ -29,24 +29,30 @@ import org.springframework.beans.factory.InitializingBean; import org.springframework.util.Assert; /** - *

Abstract base class for driving query input sources. Input Sources of - * this type use a 'driving query' to return back a list of keys. Upon each - * call to read, a new key is returned.

- * - *

Mutability: Because this base class cannot guarantee that the keys returned + *

+ * Convenience class for driving query input sources. Input Sources of this type + * use a 'driving query' to return back a list of keys. Upon each call to read, + * a new key is returned. To use the input source, inject a key generation + * strategy. + *

+ * + *

+ * Mutability: Because this base class cannot guarantee that the keys returned * by subclasses are immutable, care should be taken to not modify a key value. - * Doing so would cause issues if a rollback occurs. For example, if a call - * to read() is made, and the returned key is modified, a rollback will cause - * the next call to read() to return the same object that was originally returned, - * since there is no way to create a defensive copy, and re-querying the database - * for all the keys would be too resource intensive.

- * - * + * Doing so would cause issues if a rollback occurs. For example, if a call to + * read() is made, and the returned key is modified, a rollback will cause the + * next call to read() to return the same object that was originally returned, + * since there is no way to create a defensive copy, and re-querying the + * database for all the keys would be too resource intensive. + *

+ * + * * @author Lucas Ward * @since 1.0 */ -public class DrivingQueryInputSource extends AbstractTransactionalIoSource implements InputSource, - ResourceLifecycle, InitializingBean, DisposableBean, Restartable { +public class DrivingQueryInputSource extends AbstractTransactionalIoSource + implements InputSource, ResourceLifecycle, InitializingBean, + DisposableBean, Restartable { private boolean initialized = false; @@ -57,29 +63,30 @@ public class DrivingQueryInputSource extends AbstractTransactionalIoSource imple private int currentIndex = 0; private int lastCommitIndex = 0; - + private KeyGenerator keyGenerator; - public DrivingQueryInputSource() { - + public DrivingQueryInputSource() { + } - + /** * Initialize the input source with the provided keys list. * * @param keys */ - public DrivingQueryInputSource(List keys) { + public DrivingQueryInputSource(List keys) { this.keys = keys; this.keysIterator = keys.iterator(); } - /** - * Return the next key in the List. If the InputSource has not been initialized yet, - * then {@link AbstractDrivingQueryInputSource.open()} will be called. - * - * @return next key in the list if not index is not at the last element, null otherwise. + * Return the next key in the List. If the InputSource has not been + * initialized yet, then {@link AbstractDrivingQueryInputSource.open()} will + * be called. + * + * @return next key in the list if not index is not at the last element, + * null otherwise. */ public Object read() { if (!initialized) { @@ -95,15 +102,14 @@ public class DrivingQueryInputSource extends AbstractTransactionalIoSource imple } /** - * Get the current key. This method will return the same - * object returned by the last read() method. If the - * InputSource hasn't been initialized yet, then null will - * be returned. - * + * Get the current key. This method will return the same object returned by + * the last read() method. If the InputSource hasn't been initialized yet, + * then null will be returned. + * * @return the current key. */ - protected Object getCurrentKey(){ - if(initialized){ + protected Object getCurrentKey() { + if (initialized) { return keys.get(currentIndex - 1); } @@ -111,8 +117,8 @@ public class DrivingQueryInputSource extends AbstractTransactionalIoSource imple } /** - * Close the resource by setting the list of keys to null, allowing them - * to be garbage collected. + * Close the resource by setting the list of keys to null, allowing them to + * be garbage collected. */ public void close() { initialized = false; @@ -123,24 +129,28 @@ public class DrivingQueryInputSource extends AbstractTransactionalIoSource imple } /** - * Initialize the input source by delegating to the subclass in order to retrieve - * the keys. The input source will also be registered with the - * {@link BatchTransactionSynchronizationManager} in order to ensure it is notified - * about commits and rollbacks. - * - * @throws IllegalStateException if the keys list is null or initialized is true. + * Initialize the input source by delegating to the subclass in order to + * retrieve the keys. The input source will also be registered with the + * {@link BatchTransactionSynchronizationManager} in order to ensure it is + * notified about commits and rollbacks. + * + * @throws IllegalStateException + * if the keys list is null or initialized is true. */ public void open() { - Assert.state(keys == null || initialized, "Cannot open an already opened input source" + - ", call close() first."); + Assert.state(keys == null || initialized, + "Cannot open an already opened input source" + + ", call close() first."); keys = keyGenerator.retrieveKeys(); keysIterator = keys.listIterator(); super.registerSynchronization(); initialized = true; } - /* (non-Javadoc) + /* + * (non-Javadoc) + * * @see org.springframework.beans.factory.DisposableBean#destroy() */ public void destroy() throws Exception { @@ -155,16 +165,20 @@ public class DrivingQueryInputSource extends AbstractTransactionalIoSource imple * data could be returned. The RestartData attempting to be restored from * must have been obtained from the same input source as the one * being restored from otherwise it is invalid. - * - * @throws IllegalArgumentException if restart data or it's properties is null. - * @throws IllegalStateException if the input source has already been initialized. + * + * @throws IllegalArgumentException + * if restart data or it's properties is null. + * @throws IllegalStateException + * if the input source has already been initialized. */ public final void restoreFrom(RestartData data) { Assert.notNull(data, "RestartData must not be null."); - Assert.notNull(data.getProperties(), "RestartData properties must not be null."); - Assert.state(!initialized, "Cannot restore when already intialized. Call" - + " close() first before restore()"); + Assert.notNull(data.getProperties(), + "RestartData properties must not be null."); + Assert.state(!initialized, + "Cannot restore when already intialized. Call" + + " close() first before restore()"); if (data.getProperties().size() == 0) { return; @@ -172,7 +186,7 @@ public class DrivingQueryInputSource extends AbstractTransactionalIoSource imple keys = keyGenerator.restoreKeys(data); - if(keys != null && keys.size() > 0){ + if (keys != null && keys.size() > 0) { keysIterator = keys.listIterator(); initialized = true; } @@ -181,18 +195,17 @@ public class DrivingQueryInputSource extends AbstractTransactionalIoSource imple public RestartData getRestartData() { return keyGenerator.getKeyAsRestartData(getCurrentKey()); } - + public void afterPropertiesSet() throws Exception { Assert.notNull(keyGenerator, "The KeyGenerator must not be null."); } - + /** * Set the key generation strategy to use for this input source. * * @param keyGenerator */ - public void setKeyGenerator( - KeyGenerator keyGenerator) { + public void setKeyGenerator(KeyGenerator keyGenerator) { this.keyGenerator = keyGenerator; }