commit 2215dddc699b340df760a85a3689fd7bcf304715 Author: Dave Syer Date: Tue Dec 21 17:03:23 2010 +0000 Initial port from Spring Batch - no tests diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c73cd9a --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +target +.springBeans +.settings +.classpath +.project + diff --git a/pom.xml b/pom.xml new file mode 100644 index 0000000..853f188 --- /dev/null +++ b/pom.xml @@ -0,0 +1,156 @@ + + + 4.0.0 + org.springframework + spring-retry + 1.0.0.BUILD-SNAPSHOT + Spring Retry + http://www.springsource.org + jar + + true + 3.0.5.RELEASE + + + + strict + + false + + + + fast + + true + true + + + + staging + + + spring-site-staging + file:///${java.io.tmpdir}/spring-amqp/docs + + + spring-milestone-staging + file:///${java.io.tmpdir}/spring-amqp/milestone + + + spring-snapshot-staging + file:///${java.io.tmpdir}/spring-amqp/snapshot + + + + + + + + http://www.springsource.com/download/community + + + spring-docs + scp://static.springframework.org/var/www/domains/springframework.org/static/htdocs/spring-retry/docs/${project.version} + + + + spring-milestone + Spring Milestone Repository + s3://maven.springframework.org/milestone + + + spring-snapshot + Spring Snapshot Repository + s3://maven.springframework.org/snapshot + + + + + + junit + junit + 4.8.2 + test + + + org.springframework + spring-test + ${spring.framework.version} + test + + + org.springframework + spring-context + ${spring.framework.version} + + + log4j + log4j + 1.2.14 + + + + + + + + maven-assembly-plugin + false + + + project + + + + + org.apache.maven.plugins + maven-jar-plugin + + + target/classes/META-INF/MANIFEST.MF + + + + + + + + org.apache.maven.plugins + maven-compiler-plugin + + 1.5 + 1.5 + + + + org.apache.maven.plugins + maven-surefire-plugin + + + + **/*Tests.java + + + **/Abstract*.java + + + + + com.springsource.bundlor + com.springsource.bundlor.maven + 1.0.0.RELEASE + true + + + bundlor + + bundlor + + + + + + + diff --git a/src/main/java/org/springframework/commons/classify/BinaryExceptionClassifier.java b/src/main/java/org/springframework/commons/classify/BinaryExceptionClassifier.java new file mode 100644 index 0000000..ebfbfa4 --- /dev/null +++ b/src/main/java/org/springframework/commons/classify/BinaryExceptionClassifier.java @@ -0,0 +1,91 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ +package org.springframework.commons.classify; + +import java.util.Collection; +import java.util.HashMap; +import java.util.Map; + +/** + * A {@link Classifier} for exceptions that has only two classes (true and + * false). Classifies objects according to their inheritance relation with the + * supplied types. If the object to be classified is one of the provided types, + * or is a subclass of one of the types, then the non-default value is returned + * (usually true). + * + * @see SubclassClassifier + * + * @author Dave Syer + * + */ +public class BinaryExceptionClassifier extends SubclassClassifier { + + /** + * Create a binary exception classifier with the provided default value. + * + * @param defaultValue defaults to false + */ + public BinaryExceptionClassifier(boolean defaultValue) { + super(defaultValue); + } + + /** + * Create a binary exception classifier with the provided classes and their + * subclasses. The mapped value for these exceptions will be the one + * provided (which will be the opposite of the default). + * + * @param value + */ + public BinaryExceptionClassifier(Collection> exceptionClasses, boolean value) { + this(!value); + if (exceptionClasses != null) { + Map, Boolean> map = new HashMap, Boolean>(); + for (Class type : exceptionClasses) { + map.put(type, !getDefault()); + } + setTypeMap(map); + } + } + + /** + * Create a binary exception classifier with the default value false and + * value mapping true for the provided classes and their subclasses. + */ + public BinaryExceptionClassifier(Collection> exceptionClasses) { + this(exceptionClasses, true); + } + + /** + * Create a binary exception classifier using the given classification map + * and a default classification of false. + * + * @param typeMap + */ + public BinaryExceptionClassifier(Map, Boolean> typeMap) { + this(typeMap, false); + } + + /** + * Create a binary exception classifier using the given classification map + * and a default classification of false. + * + * @param typeMap + */ + public BinaryExceptionClassifier(Map, Boolean> typeMap, boolean defaultValue) { + super(typeMap, defaultValue); + } + +} diff --git a/src/main/java/org/springframework/commons/classify/Classifier.java b/src/main/java/org/springframework/commons/classify/Classifier.java new file mode 100644 index 0000000..83864ac --- /dev/null +++ b/src/main/java/org/springframework/commons/classify/Classifier.java @@ -0,0 +1,38 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.classify; + +/** + * Interface for a classifier. At its simplest a {@link Classifier} is just a + * map from objects of one type to objects of another type. + * + * @author Dave Syer + * + */ +public interface Classifier { + + /** + * Classify the given object and return an object of a different type, + * possibly an enumerated type. + * + * @param classifiable the input object. Can be null. + * @return an object. Can be null, but implementations should declare if + * this is the case. + */ + T classify(C classifiable); + +} diff --git a/src/main/java/org/springframework/commons/classify/ClassifierSupport.java b/src/main/java/org/springframework/commons/classify/ClassifierSupport.java new file mode 100644 index 0000000..c76877c --- /dev/null +++ b/src/main/java/org/springframework/commons/classify/ClassifierSupport.java @@ -0,0 +1,48 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.classify; + +/** + * Base class for {@link Classifier} implementations. Provides default behaviour + * and some convenience members, like constants. + * + * @author Dave Syer + * + */ +public class ClassifierSupport implements Classifier { + + final private T defaultValue; + + /** + * @param defaultValue + */ + public ClassifierSupport(T defaultValue) { + super(); + this.defaultValue = defaultValue; + } + + /** + * Always returns the default value. This is the main extension point for + * subclasses, so it must be able to classify null. + * + * @see org.springframework.commons.classify.Classifier#classify(Object) + */ + public T classify(C throwable) { + return defaultValue; + } + +} diff --git a/src/main/java/org/springframework/commons/classify/SubclassClassifier.java b/src/main/java/org/springframework/commons/classify/SubclassClassifier.java new file mode 100644 index 0000000..f23deb6 --- /dev/null +++ b/src/main/java/org/springframework/commons/classify/SubclassClassifier.java @@ -0,0 +1,148 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ +package org.springframework.commons.classify; + +import java.io.Serializable; +import java.util.Comparator; +import java.util.HashMap; +import java.util.Map; +import java.util.Set; +import java.util.TreeSet; + +/** + * A {@link Classifier} for a parameterised object type based on a map. + * Classifies objects according to their inheritance relation with the supplied + * type map. If the object to be classified is one of the keys of the provided + * map, or is a subclass of one of the keys, then the map entry vale for that + * key is returned. Otherwise returns the default value which is null by + * default. + * + * @author Dave Syer + * + */ +public class SubclassClassifier implements Classifier { + + private Map, C> classified = new HashMap, C>(); + + private C defaultValue = null; + + /** + * Create a {@link SubclassClassifier} with null default value. + * + */ + public SubclassClassifier() { + this(null); + } + + /** + * Create a {@link SubclassClassifier} with supplied default value. + * + * @param defaultValue + */ + public SubclassClassifier(C defaultValue) { + this(new HashMap, C>(), defaultValue); + } + + /** + * Create a {@link SubclassClassifier} with supplied default value. + * + * @param defaultValue + */ + public SubclassClassifier(Map, C> typeMap, C defaultValue) { + super(); + this.classified = new HashMap, C>(typeMap); + this.defaultValue = defaultValue; + } + + /** + * Public setter for the default value for mapping keys that are not found + * in the map (or their subclasses). Defaults to false. + * + * @param defaultValue the default value to set + */ + public void setDefaultValue(C defaultValue) { + this.defaultValue = defaultValue; + } + + /** + * Set the classifications up as a map. The keys are types and these will be + * mapped along with all their subclasses to the corresponding value. The + * most specific types will match first. + * + * @param map a map from type to class + */ + public void setTypeMap(Map, C> map) { + this.classified = new HashMap, C>(map); + } + + /** + * Return the value from the type map whose key is the class of the given + * Throwable, or its nearest ancestor if a subclass. + * + */ + public C classify(T classifiable) { + + if (classifiable == null) { + return defaultValue; + } + + @SuppressWarnings("unchecked") + Class exceptionClass = (Class) classifiable.getClass(); + if (classified.containsKey(exceptionClass)) { + return classified.get(exceptionClass); + } + + // check for subclasses + Set> classes = new TreeSet>(new ClassComparator()); + classes.addAll(classified.keySet()); + for (Class cls : classes) { + if (cls.isAssignableFrom(exceptionClass)) { + C value = classified.get(cls); + this.classified.put(exceptionClass, value); + return value; + } + } + + return defaultValue; + } + + /** + * Return the default value supplied in the constructor (default false). + */ + final public C getDefault() { + return defaultValue; + } + + /** + * Comparator for classes to order by inheritance. + * + * @author Dave Syer + * + */ + private static class ClassComparator implements Comparator>, Serializable { + /** + * @return 1 if arg0 is assignable from arg1, -1 otherwise + * @see java.util.Comparator#compare(java.lang.Object, java.lang.Object) + */ + public int compare(Class arg0, Class arg1) { + if (arg0.isAssignableFrom(arg1)) { + return 1; + } + return -1; + } + } + +} diff --git a/src/main/java/org/springframework/commons/repeat/RepeatCallback.java b/src/main/java/org/springframework/commons/repeat/RepeatCallback.java new file mode 100644 index 0000000..2e5d426 --- /dev/null +++ b/src/main/java/org/springframework/commons/repeat/RepeatCallback.java @@ -0,0 +1,44 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.repeat; + + +/** + * Callback interface for batch operations. Many simple processes will be able + * to use off-the-shelf implementations of this interface, enabling the + * application developer to concentrate on business logic. + * + * @see RepeatOperations + * + * @author Dave Syer + * + */ +public interface RepeatCallback { + + /** + * Implementations return true if they can continue processing - e.g. there + * is a data source that is not yet exhausted. Exceptions are not necessarily + * fatal - processing might continue depending on the Exception type and the + * implementation of the caller. + * + * @param context the current context passed in by the caller. + * @return an {@link RepeatStatus} which is continuable if there is (or may + * be) more data to process. + * @throws Exception if there is a problem with the processing. + */ + RepeatStatus doInIteration(RepeatContext context) throws Exception; +} diff --git a/src/main/java/org/springframework/commons/repeat/RepeatContext.java b/src/main/java/org/springframework/commons/repeat/RepeatContext.java new file mode 100644 index 0000000..099cf8a --- /dev/null +++ b/src/main/java/org/springframework/commons/repeat/RepeatContext.java @@ -0,0 +1,91 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.repeat; + +import org.springframework.core.AttributeAccessor; + +/** + * Base interface for context which controls the state and completion / + * termination of a batch step. A new context is created for each call to the + * {@link RepeatOperations}. Within a batch callback code can communicate via + * the {@link AttributeAccessor} interface. + * + * @author Dave Syer + * + * @see RepeatOperations#iterate(RepeatCallback) + * + */ +public interface RepeatContext extends AttributeAccessor { + + /** + * If batches are nested, then the inner batch will be created with the + * outer one as a parent. This is an accessor for the parent if it exists. + * + * @return the parent context or null if there is none + */ + RepeatContext getParent(); + + /** + * Public access to a counter for the number of operations attempted. + * + * @return the number of batch operations started. + */ + int getStartedCount(); + + /** + * Signal to the framework that the current batch should complete normally, + * independent of the current {@link CompletionPolicy}. + */ + void setCompleteOnly(); + + /** + * Public accessor for the complete flag. + */ + boolean isCompleteOnly(); + + /** + * Signal to the framework that the current batch should complete + * abnormally, independent of the current {@link CompletionPolicy}. + */ + void setTerminateOnly(); + + /** + * Public accessor for the termination flag. If this flag is set then the + * complete flag will also be. + */ + boolean isTerminateOnly(); + + /** + * Register a callback to be executed on close, associated with the + * attribute having the given name. The {@link Runnable} callback should not + * throw any exceptions. + * + * @param name the name of the attribute to associated this callback with. + * If this attribute is removed the callback should never be called. + * @param callback a {@link Runnable} to execute when the context is closed. + */ + void registerDestructionCallback(String name, Runnable callback); + + /** + * Allow resources to be cleared, especially in destruction callbacks. + * Implementations should ensure that any registered destruction callbacks + * are executed here, as long as the corresponding attribute is still + * available. + */ + void close(); + +} diff --git a/src/main/java/org/springframework/commons/repeat/RepeatException.java b/src/main/java/org/springframework/commons/repeat/RepeatException.java new file mode 100644 index 0000000..8e110b0 --- /dev/null +++ b/src/main/java/org/springframework/commons/repeat/RepeatException.java @@ -0,0 +1,31 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.repeat; + +import org.springframework.core.NestedRuntimeException; + +public class RepeatException extends NestedRuntimeException { + + public RepeatException(String msg) { + super(msg); + } + + public RepeatException(String msg, Throwable t) { + super(msg, t); + } + +} diff --git a/src/main/java/org/springframework/commons/repeat/RepeatOperations.java b/src/main/java/org/springframework/commons/repeat/RepeatOperations.java new file mode 100644 index 0000000..da49ee2 --- /dev/null +++ b/src/main/java/org/springframework/commons/repeat/RepeatOperations.java @@ -0,0 +1,47 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.repeat; + + +/** + * The main interface providing access to batch operations. The batch client is + * the {@link RepeatCallback}, where a single item or record is processed. The + * batch behaviour, boundary conditions, transactions etc, are dealt with by the + * {@link RepeatOperations} in such as way that the client does not need to know + * about them. The client may have access to framework abstractions, like + * template data sources, but these should work the same whether they are in a + * batch or not. + * + * @author Dave Syer + * + */ +public interface RepeatOperations { + + /** + * Execute the callback repeatedly, until a decision can be made to + * complete. The decision about how many times to execute or when to + * complete, and what to do in the case of an error is delegated to a + * {@link CompletionPolicy}. + * + * @param callback the batch callback. + * @return the aggregate of the result of all the callback operations. An + * indication of whether the {@link RepeatOperations} can continue + * processing if this method is called again. + */ + RepeatStatus iterate(RepeatCallback callback) throws RepeatException; + +} diff --git a/src/main/java/org/springframework/commons/repeat/RepeatStatus.java b/src/main/java/org/springframework/commons/repeat/RepeatStatus.java new file mode 100644 index 0000000..3a117ab --- /dev/null +++ b/src/main/java/org/springframework/commons/repeat/RepeatStatus.java @@ -0,0 +1,48 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.repeat; + +public enum RepeatStatus { + + /** + * Indicates that processing can continue. + */ + CONTINUABLE(true), + /** + * Indicates that processing is finished (either successful or unsuccessful) + */ + FINISHED(false); + + private final boolean continuable; + + private RepeatStatus(boolean continuable) { + this.continuable = continuable; + } + + public static RepeatStatus continueIf(boolean continuable) { + return continuable ? CONTINUABLE : FINISHED; + } + + public boolean isContinuable() { + return this == CONTINUABLE; + } + + public RepeatStatus and(boolean value) { + return value && continuable ? CONTINUABLE : FINISHED; + } + +} diff --git a/src/main/java/org/springframework/commons/retry/ExhaustedRetryException.java b/src/main/java/org/springframework/commons/retry/ExhaustedRetryException.java new file mode 100644 index 0000000..2a630fd --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/ExhaustedRetryException.java @@ -0,0 +1,29 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry; + +public class ExhaustedRetryException extends RetryException { + + public ExhaustedRetryException(String msg, Throwable cause) { + super(msg, cause); + } + + public ExhaustedRetryException(String msg) { + super(msg); + } + +} diff --git a/src/main/java/org/springframework/commons/retry/RecoveryCallback.java b/src/main/java/org/springframework/commons/retry/RecoveryCallback.java new file mode 100644 index 0000000..d158dc8 --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/RecoveryCallback.java @@ -0,0 +1,35 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ +package org.springframework.commons.retry; + +/** + * Callback for stateful retry after all tries are exhausted. + * + * @author Dave Syer + * + * @since 1.1 + */ +public interface RecoveryCallback { + + /** + * @param context the current retry context + * @return an Object that can be used to replace the callback result that + * failed + * @throws Exception + */ + T recover(RetryContext context) throws Exception; + +} diff --git a/src/main/java/org/springframework/commons/retry/RetryCallback.java b/src/main/java/org/springframework/commons/retry/RetryCallback.java new file mode 100644 index 0000000..167fe68 --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/RetryCallback.java @@ -0,0 +1,37 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry; + +/** + * Callback interface for an operation that can be retried using a + * {@link RetryOperations}. + * + * @author Rob Harrop + * @author Dave Syer + */ +public interface RetryCallback { + + /** + * Execute an operation with retry semantics. Operations should generally be + * idempotent, but implementations may choose to implement compensation + * semantics when an operation is retried. + * @param context the current retry context. + * @return the result of the successful operation. + * @throws Exception if processing fails + */ + T doWithRetry(RetryContext context) throws Exception; +} diff --git a/src/main/java/org/springframework/commons/retry/RetryContext.java b/src/main/java/org/springframework/commons/retry/RetryContext.java new file mode 100644 index 0000000..d785066 --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/RetryContext.java @@ -0,0 +1,69 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry; + +import org.springframework.core.AttributeAccessor; + +/** + * Low-level access to ongoing retry operation. Normally not needed by clients, + * but can be used to alter the course of the retry, e.g. force an early + * termination. + * + * @author Dave Syer + * + */ +public interface RetryContext extends AttributeAccessor { + + /** + * Signal to the framework that no more attempts should be made to try or + * retry the current {@link RetryCallback}. + */ + void setExhaustedOnly(); + + /** + * Public accessor for the exhausted flag {@link #setExhaustedOnly()}. + * + * @return true if the flag has been set. + */ + boolean isExhaustedOnly(); + + /** + * Accessor for the parent context if retry blocks are nested. + * + * @return the parent or null if there is none. + */ + RetryContext getParent(); + + /** + * Counts the number of retry attempts. Before the first attempt this + * counter is zero, and before the first and subsequent attempts it should + * increment accordingly. + * + * @return the number of retries. + */ + int getRetryCount(); + + /** + * Accessor for the exception object that caused the current retry. + * + * @return the last exception that caused a retry, or possibly null. It will + * be null if this is the first attempt, but also if the enclosing policy + * decides not to provide it (e.g. because of concerns about memory usage). + */ + Throwable getLastThrowable(); + +} diff --git a/src/main/java/org/springframework/commons/retry/RetryException.java b/src/main/java/org/springframework/commons/retry/RetryException.java new file mode 100644 index 0000000..92900be --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/RetryException.java @@ -0,0 +1,31 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry; + +import org.springframework.core.NestedRuntimeException; + +public class RetryException extends NestedRuntimeException { + + public RetryException(String msg, Throwable cause) { + super(msg, cause); + } + + public RetryException(String msg) { + super(msg); + } + +} diff --git a/src/main/java/org/springframework/commons/retry/RetryListener.java b/src/main/java/org/springframework/commons/retry/RetryListener.java new file mode 100644 index 0000000..d8499c3 --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/RetryListener.java @@ -0,0 +1,62 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry; + + +/** + * Interface for listener that can be used to add behaviour to a retry. + * Implementations of {@link RetryOperations} can chose to issue callbacks to an + * interceptor during the retry lifecycle. + * + * @author Dave Syer + * + */ +public interface RetryListener { + + /** + * Called before the first attempt in a retry. For instance, implementers + * can set up state that is needed by the policies in the + * {@link RetryOperations}. The whole retry can be vetoed by returning + * false from this method, in which case a {@link TerminatedRetryException} + * will be thrown. + * + * @param context the current {@link RetryContext}. + * @param callback the current {@link RetryCallback}. + * @return true if the retry should proceed. + */ + boolean open(RetryContext context, RetryCallback callback); + + /** + * Called after the final attempt (successful or not). Allow the interceptor + * to clean up any resource it is holding before control returns to the + * retry caller. + * + * @param context the current {@link RetryContext}. + * @param callback the current {@link RetryCallback}. + * @param throwable the last exception that was thrown by the callback. + */ + void close(RetryContext context, RetryCallback callback, Throwable throwable); + + /** + * Called after every unsuccessful attempt at a retry. + * + * @param context the current {@link RetryContext}. + * @param callback the current {@link RetryCallback}. + * @param throwable the last exception that was thrown by the callback. + */ + void onError(RetryContext context, RetryCallback callback, Throwable throwable); +} diff --git a/src/main/java/org/springframework/commons/retry/RetryOperations.java b/src/main/java/org/springframework/commons/retry/RetryOperations.java new file mode 100644 index 0000000..f77e825 --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/RetryOperations.java @@ -0,0 +1,89 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry; + +import org.springframework.commons.retry.support.DefaultRetryState; + +/** + * Defines the basic set of operations implemented by {@link RetryOperations} to + * execute operations with configurable retry behaviour. + * + * @author Rob Harrop + * @author Dave Syer + */ +public interface RetryOperations { + + /** + * Execute the supplied {@link RetryCallback} with the configured retry + * semantics. See implementations for configuration details. + * + * @return the value returned by the {@link RetryCallback} upon successful + * invocation. + * @throws Exception any {@link Exception} raised by the + * {@link RetryCallback} upon unsuccessful retry. + */ + T execute(RetryCallback retryCallback) throws Exception; + + /** + * Execute the supplied {@link RetryCallback} with a fallback on exhausted + * retry to the {@link RecoveryCallback}. See implementations for + * configuration details. + * + * @return the value returned by the {@link RetryCallback} upon successful + * invocation, and that returned by the {@link RecoveryCallback} otherwise. + * @throws Exception any {@link Exception} raised by the + * {@link RecoveryCallback} upon unsuccessful retry. + */ + T execute(RetryCallback retryCallback, RecoveryCallback recoveryCallback) throws Exception; + + /** + * A simple stateful retry. Execute the supplied {@link RetryCallback} with + * a target object for the attempt identified by the {@link DefaultRetryState}. + * Exceptions thrown by the callback are always propagated immediately so + * the state is required to be able to identify the previous attempt, if + * there is one - hence the state is required. Normal patterns would see + * this method being used inside a transaction, where the callback might + * invalidate the transaction if it fails.

+ * + * See implementations for configuration details. + * + * @return the value returned by the {@link RetryCallback} upon successful + * invocation, and that returned by the {@link RecoveryCallback} otherwise. + * @throws Exception any {@link Exception} raised by the + * {@link RecoveryCallback}. + * @throws ExhaustedRetryException if the last attempt for this state has + * already been reached + */ + T execute(RetryCallback retryCallback, RetryState retryState) throws Exception, ExhaustedRetryException; + + /** + * A stateful retry with a recovery path. Execute the supplied + * {@link RetryCallback} with a fallback on exhausted retry to the + * {@link RecoveryCallback} and a target object for the retry attempt + * identified by the {@link DefaultRetryState}. + * + * @see #execute(RetryCallback, RetryState) + * + * @return the value returned by the {@link RetryCallback} upon successful + * invocation, and that returned by the {@link RecoveryCallback} otherwise. + * @throws Exception any {@link Exception} raised by the + * {@link RecoveryCallback} upon unsuccessful retry. + */ + T execute(RetryCallback retryCallback, RecoveryCallback recoveryCallback, RetryState retryState) + throws Exception; + +} diff --git a/src/main/java/org/springframework/commons/retry/RetryPolicy.java b/src/main/java/org/springframework/commons/retry/RetryPolicy.java new file mode 100644 index 0000000..273f870 --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/RetryPolicy.java @@ -0,0 +1,63 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry; + +/** + * A {@link RetryPolicy} is responsible for allocating and managing resources + * needed by {@link RetryOperations}. The {@link RetryPolicy} allows retry + * operations to be aware of their context. Context can be internal to the retry + * framework, e.g. to support nested retries. Context can also be external, and + * the {@link RetryPolicy} provides a uniform API for a range of different + * platforms for the external context. + * + * @author Dave Syer + * + */ +public interface RetryPolicy { + + /** + * @param context the current retry status + * @return true if the operation can proceed + */ + boolean canRetry(RetryContext context); + + /** + * Acquire resources needed for the retry operation. The callback is passed + * in so that marker interfaces can be used and a manager can collaborate + * with the callback to set up some state in the status token. + * @param parent the parent context if we are in a nested retry. + * + * @return a {@link RetryContext} object specific to this manager. + * + */ + RetryContext open(RetryContext parent); + + /** + * @param context a retry status created by the + * {@link #open(RetryContext)} method of this manager. + */ + void close(RetryContext context); + + /** + * Called once per retry attempt, after the callback fails. + * + * @param context the current status object. + * + */ + void registerThrowable(RetryContext context, Throwable throwable); + +} diff --git a/src/main/java/org/springframework/commons/retry/RetryState.java b/src/main/java/org/springframework/commons/retry/RetryState.java new file mode 100644 index 0000000..6dd1331 --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/RetryState.java @@ -0,0 +1,60 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ +package org.springframework.commons.retry; + +/** + * Stateful retry is characterised by having to recognise the items that are + * being processed, so this interface is used primarily to provide a cache key in + * between failed attempts. It also provides a hints to the + * {@link RetryOperations} for optimisations to do with avoidable cache hits and + * switching to stateless retry if a rollback is not needed. + * + * @author Dave Syer + * + */ +public interface RetryState { + + /** + * Key representing the state for a retry attempt. Stateful retry is + * characterised by having to recognise the items that are being processed, + * so this value is used as a cache key in between failed attempts. + * + * @return the key that this state represents + */ + Object getKey(); + + /** + * Indicate whether a cache lookup can be avoided. If the key is known ahead + * of the retry attempt to be fresh (i.e. has never been seen before) then a + * cache lookup can be avoided if this flag is true. + * + * @return true if the state does not require an explicit check for the key + */ + boolean isForceRefresh(); + + /** + * Check whether this exception requires a rollback. The default is always + * true, which is conservative, so this method provides an optimisation for + * switching to stateless retry if there is an exception for which rollback + * is unnecessary. Example usage would be for a stateful retry to specify a + * validation exception as not for rollback. + * + * @param exception the exception that caused a retry attempt to fail + * @return true if this exception should cause a rollback + */ + boolean rollbackFor(Throwable exception); + +} \ No newline at end of file diff --git a/src/main/java/org/springframework/commons/retry/RetryStatistics.java b/src/main/java/org/springframework/commons/retry/RetryStatistics.java new file mode 100644 index 0000000..098220d --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/RetryStatistics.java @@ -0,0 +1,64 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry; + +/** + * Interface for statistics reporting of retry attempts. Counts the number of + * retry attempts, successes, errors (including retries), and aborts. + * + * @author Dave Syer + * + */ +public interface RetryStatistics { + + /** + * @return the number of completed retry attempts (successful or not). + */ + int getCompleteCount(); + + /** + * Get the number of times a retry block has been entered, irrespective of + * how many times the operation was retried. + * + * @return the number of retry blocks started. + */ + int getStartedCount(); + + /** + * Get the number of errors detected, whether or not they resulted in a + * retry. + * + * @return the number of errors detected. + */ + int getErrorCount(); + + /** + * Get the number of times a block failed to complete successfully, even + * after retry. + * + * @return the number of retry attempts that failed overall. + */ + int getAbortCount(); + + /** + * Get an identifier for the retry block for reporting purposes. + * + * @return an identifier for the block. + */ + String getName(); + +} diff --git a/src/main/java/org/springframework/commons/retry/TerminatedRetryException.java b/src/main/java/org/springframework/commons/retry/TerminatedRetryException.java new file mode 100644 index 0000000..6642bb7 --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/TerminatedRetryException.java @@ -0,0 +1,29 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry; + +public class TerminatedRetryException extends RetryException { + + public TerminatedRetryException(String msg, Throwable cause) { + super(msg, cause); + } + + public TerminatedRetryException(String msg) { + super(msg); + } + +} diff --git a/src/main/java/org/springframework/commons/retry/backoff/BackOffContext.java b/src/main/java/org/springframework/commons/retry/backoff/BackOffContext.java new file mode 100644 index 0000000..6f445a2 --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/backoff/BackOffContext.java @@ -0,0 +1,25 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry.backoff; + +/** + * @author Rob Harrop + * @since 2.1 + */ +public interface BackOffContext { + +} diff --git a/src/main/java/org/springframework/commons/retry/backoff/BackOffInterruptedException.java b/src/main/java/org/springframework/commons/retry/backoff/BackOffInterruptedException.java new file mode 100644 index 0000000..9a84e1b --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/backoff/BackOffInterruptedException.java @@ -0,0 +1,38 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry.backoff; + +import org.springframework.commons.retry.RetryException; + +/** + * Exception class signifiying that an attempt to back off using a + * {@link BackOffPolicy} was interrupted, most likely by an + * {@link InterruptedException} during a call to {@link Thread#sleep(long)}. + * + * @author Rob Harrop + * @since 2.1 + */ +public class BackOffInterruptedException extends RetryException { + + public BackOffInterruptedException(String msg) { + super(msg); + } + + public BackOffInterruptedException(String msg, Throwable cause) { + super(msg, cause); + } +} diff --git a/src/main/java/org/springframework/commons/retry/backoff/BackOffPolicy.java b/src/main/java/org/springframework/commons/retry/backoff/BackOffPolicy.java new file mode 100644 index 0000000..14c7857 --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/backoff/BackOffPolicy.java @@ -0,0 +1,61 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry.backoff; + +import org.springframework.commons.retry.RetryContext; + +/** + * Strategy interface to control back off between attempts in a single + * {@link org.springframework.commons.retry.support.RetryTemplate retry operation}. + *

Implementations are expected to be thread-safe and should be designed + * for concurrent access. Configuration for each implementation is also expected + * to be thread-safe but need not be suitable for high load concurrent access. + *

For each block of retry operations the {@link #start} method is called + * and implementations can return an implementation-specific + * {@link BackOffContext} that can be used to track state through subsequent + * back off invocations.

Each back off process is handled via a call to + * {@link #backOff}. The + * {@link org.springframework.commons.retry.support.RetryTemplate} will pass in + * the corresponding {@link BackOffContext} object created by the call to + * {@link #start}. + * + * @author Rob Harrop + * @author Dave Syer + */ +public interface BackOffPolicy { + + /** + * Start a new block of back off operations. Implementations can choose to + * pause when this method is called, but normally it returns immediately. + * + * @param context the current retry context, which might contain information + * that we can use to decide how to proceed. + * @return the implementation-specific {@link BackOffContext} or 'null'. + */ + BackOffContext start(RetryContext context); + + /** + * Back off/pause in an implementation-specific fashion. The passed in + * {@link BackOffContext} corresponds to the one created by the call to + * {@link #start} for a given retry operation set. + * + * @throws BackOffInterruptedException if the attempt at back off is + * interrupted. + */ + void backOff(BackOffContext backOffContext) throws BackOffInterruptedException; + +} diff --git a/src/main/java/org/springframework/commons/retry/backoff/ExponentialBackOffPolicy.java b/src/main/java/org/springframework/commons/retry/backoff/ExponentialBackOffPolicy.java new file mode 100644 index 0000000..b286e3c --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/backoff/ExponentialBackOffPolicy.java @@ -0,0 +1,192 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry.backoff; + +import org.springframework.commons.retry.RetryContext; +import org.springframework.util.ClassUtils; + +/** + * Implementation of {@link BackOffPolicy} that increases the back off period + * for each retry attempt in a given set using the {@link Math#exp(double) + * exponential} function. + *

+ * This implementation is thread-safe and suitable for concurrent access. + * Modifications to the configuration do not affect any retry sets that are + * already in progress. + *

+ * The {@link #setInitialInterval(long)} property controls the initial value + * passed to {@link Math#exp(double)} and the {@link #setMultiplier(double)} + * property controls by how much this value is increased for each subsequent + * attempt. + * + * @author Rob Harrop + * @author Dave Syer + */ +public class ExponentialBackOffPolicy implements BackOffPolicy { + + /** + * The default 'initialInterval' value - 100 millisecs. Coupled with the + * default 'multiplier' value this gives a useful initial spread of pauses + * for 1-5 retries. + */ + public static final long DEFAULT_INITIAL_INTERVAL = 100L; + + /** + * The default maximum backoff time (30 seconds). + */ + public static final long DEFAULT_MAX_INTERVAL = 30000L; + + /** + * The default 'multiplier' value - value 2 (100% increase per backoff). + */ + public static final double DEFAULT_MULTIPLIER = 2; + + /** + * The initial sleep interval. + */ + private volatile long initialInterval = DEFAULT_INITIAL_INTERVAL; + + /** + * The maximum value of the backoff period in milliseconds. + */ + private volatile long maxInterval = DEFAULT_MAX_INTERVAL; + + /** + * The value to increment the exp seed with for each retry attempt. + */ + private volatile double multiplier = DEFAULT_MULTIPLIER; + + private Sleeper sleeper = new ObjectWaitSleeper(); + + /** + * Public setter for the {@link Sleeper} strategy. + * @param sleeper the sleeper to set defaults to {@link ObjectWaitSleeper}. + */ + public void setSleeper(Sleeper sleeper) { + this.sleeper = sleeper; + } + + /** + * Set the initial sleep interval value. Default is 100 + * millisecond. Cannot be set to a value less than one. + */ + public void setInitialInterval(long initialInterval) { + this.initialInterval = (initialInterval > 1 ? initialInterval : 1); + } + + /** + * Set the multiplier value. Default is '2.0'. Hint: do not use + * values much in excess of 1.0 (or the backoff will get very long very + * fast). + */ + public void setMultiplier(double multiplier) { + this.multiplier = (multiplier > 1.0 ? multiplier : 1.0); + } + + /** + * Setter for maximum back off period. Default is 30000 (30 seconds). the + * value will be reset to 1 if this method is called with a value less than + * 1. Set this to avoid infinite waits if backing off a large number of + * times (or if the multiplier is set too high). + * + * @param maxInterval in milliseconds. + */ + public void setMaxInterval(long maxInterval) { + this.maxInterval = maxInterval > 0 ? maxInterval : 1; + } + + /** + * The initial period to sleep on the first backoff. + * @return the initial interval + */ + public long getInitialInterval() { + return initialInterval; + } + + /** + * The maximum interval to sleep for. Defaults to 30 seconds. + * + * @return the maximum interval. + */ + public long getMaxInterval() { + return maxInterval; + } + + /** + * The multiplier to use to generate the next backoff interval from the + * last. + * + * @return the multiplier in use + */ + public double getMultiplier() { + return multiplier; + } + + /** + * Returns a new instance of {@link BackOffContext} configured with the + * 'expSeed' and 'increment' values. + */ + public BackOffContext start(RetryContext context) { + return new ExponentialBackOffContext(this.initialInterval, this.multiplier, this.maxInterval); + } + + /** + * Pause for a length of time equal to ' + * exp(backOffContext.expSeed)'. + */ + public void backOff(BackOffContext backOffContext) throws BackOffInterruptedException { + ExponentialBackOffContext context = (ExponentialBackOffContext) backOffContext; + try { + sleeper.sleep(context.getSleepAndIncrement()); + } + catch (InterruptedException e) { + throw new BackOffInterruptedException("Thread interrupted while sleeping", e); + } + } + + private static class ExponentialBackOffContext implements BackOffContext { + + private final double multiplier; + + private long interval; + + private long maxInterval; + + public ExponentialBackOffContext(long expSeed, double multiplier, long maxInterval) { + this.interval = expSeed; + this.multiplier = multiplier; + this.maxInterval = maxInterval; + } + + public synchronized long getSleepAndIncrement() { + long sleep = this.interval; + if (sleep > maxInterval) { + sleep = (long) maxInterval; + } + else { + this.interval *= this.multiplier; + } + return sleep; + } + } + + public String toString() { + return ClassUtils.getShortName(getClass()) + "[initialInterval=" + initialInterval + ", multiplier=" + + multiplier + ", maxInterval=" + maxInterval + "]"; + } + +} diff --git a/src/main/java/org/springframework/commons/retry/backoff/FixedBackOffPolicy.java b/src/main/java/org/springframework/commons/retry/backoff/FixedBackOffPolicy.java new file mode 100644 index 0000000..ec44217 --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/backoff/FixedBackOffPolicy.java @@ -0,0 +1,81 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry.backoff; + + +/** + * Implementation of {@link BackOffPolicy} that pauses for a fixed period of + * time before continuing. A pause is implemented using {@link Thread#sleep(long)}. + *

{@link #setBackOffPeriod(long)} is thread-safe and it is safe to call + * {@link #setBackOffPeriod} during execution from multiple threads, however + * this may cause a single retry operation to have pauses of different + * intervals. + * @author Rob Harrop + * @author Dave Syer + */ +public class FixedBackOffPolicy extends StatelessBackOffPolicy { + + /** + * Default back off period - 1000ms. + */ + private static final long DEFAULT_BACK_OFF_PERIOD = 1000L; + + /** + * The back off period in milliseconds. Defaults to 1000ms. + */ + private volatile long backOffPeriod = DEFAULT_BACK_OFF_PERIOD; + + + private Sleeper sleeper = new ObjectWaitSleeper(); + + /** + * Public setter for the {@link Sleeper} strategy. + * @param sleeper the sleeper to set defaults to {@link ObjectWaitSleeper}. + */ + public void setSleeper(Sleeper sleeper) { + this.sleeper = sleeper; + } + + /** + * Set the back off period in milliseconds. Cannot be < 1. Default value + * is 1000ms. + */ + public void setBackOffPeriod(long backOffPeriod) { + this.backOffPeriod = (backOffPeriod > 0 ? backOffPeriod : 1); + } + + /** + * The backoff period in milliseconds. + * @return the backoff period + */ + public long getBackOffPeriod() { + return backOffPeriod; + } + + /** + * Pause for the {@link #setBackOffPeriod(long)}. + * @throws BackOffInterruptedException if interrupted during sleep. + */ + protected void doBackOff() throws BackOffInterruptedException { + try { + sleeper.sleep(backOffPeriod); + } + catch (InterruptedException e) { + throw new BackOffInterruptedException("Thread interrupted while sleeping", e); + } + } +} diff --git a/src/main/java/org/springframework/commons/retry/backoff/NoBackOffPolicy.java b/src/main/java/org/springframework/commons/retry/backoff/NoBackOffPolicy.java new file mode 100644 index 0000000..66c99d0 --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/backoff/NoBackOffPolicy.java @@ -0,0 +1,31 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry.backoff; + + +/** + * Implementation of {@link BackOffPolicy} that performs a no-op and as such all + * retry operation in a given set proceed one after the other with no pause. + * + * @author Rob Harrop + * @since 2.1 + */ +public class NoBackOffPolicy extends StatelessBackOffPolicy { + + protected void doBackOff() throws BackOffInterruptedException { + } +} diff --git a/src/main/java/org/springframework/commons/retry/backoff/ObjectWaitSleeper.java b/src/main/java/org/springframework/commons/retry/backoff/ObjectWaitSleeper.java new file mode 100644 index 0000000..10a88ad --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/backoff/ObjectWaitSleeper.java @@ -0,0 +1,37 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ +package org.springframework.commons.retry.backoff; + +/** + * Simple {@link Sleeper} implementation that just waits on a local Object. + * + * @author Dave Syer + * + */ +public class ObjectWaitSleeper implements Sleeper { + + /* + * (non-Javadoc) + * @see org.springframework.commons.retry.backoff.Sleeper#sleep(long) + */ + public void sleep(long backOffPeriod) throws InterruptedException { + Object mutex = new Object(); + synchronized (mutex) { + mutex.wait(backOffPeriod); + } + } + +} diff --git a/src/main/java/org/springframework/commons/retry/backoff/Sleeper.java b/src/main/java/org/springframework/commons/retry/backoff/Sleeper.java new file mode 100644 index 0000000..8eccf45 --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/backoff/Sleeper.java @@ -0,0 +1,33 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ +package org.springframework.commons.retry.backoff; + +/** + * Strategy interface for backoff policies to delegate the pausing of execution. + * + * @author Dave Syer + * + */ +public interface Sleeper { + + /** + * Pause for the specified period using whatever means available. + * + * @param backOffPeriod + */ + void sleep(long backOffPeriod) throws InterruptedException; + +} diff --git a/src/main/java/org/springframework/commons/retry/backoff/StatelessBackOffPolicy.java b/src/main/java/org/springframework/commons/retry/backoff/StatelessBackOffPolicy.java new file mode 100644 index 0000000..14ee264 --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/backoff/StatelessBackOffPolicy.java @@ -0,0 +1,51 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry.backoff; + +import org.springframework.commons.retry.RetryContext; + +/** + * Simple base class for {@link BackOffPolicy} implementations that maintain no + * state across invocations. + * + * @author Rob Harrop + * @author Dave Syer + */ +public abstract class StatelessBackOffPolicy implements BackOffPolicy { + + /** + * Delegates directly to the {@link #doBackOff()} method without passing on + * the {@link BackOffContext} argument which is not needed for stateless + * implementations. + */ + public final void backOff(BackOffContext backOffContext) throws BackOffInterruptedException { + doBackOff(); + } + + /** + * Returns 'null'. Subclasses can add behaviour, e.g. + * initial sleep before first attempt. + */ + public BackOffContext start(RetryContext status) { + return null; + } + + /** + * Sub-classes should implement this method to perform the actual back off. + */ + protected abstract void doBackOff() throws BackOffInterruptedException; +} diff --git a/src/main/java/org/springframework/commons/retry/context/RetryContextSupport.java b/src/main/java/org/springframework/commons/retry/context/RetryContextSupport.java new file mode 100644 index 0000000..0c5292a --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/context/RetryContextSupport.java @@ -0,0 +1,83 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry.context; + +import org.springframework.commons.retry.RetryContext; +import org.springframework.commons.retry.RetryPolicy; +import org.springframework.core.AttributeAccessorSupport; + +public class RetryContextSupport extends AttributeAccessorSupport implements RetryContext { + + private boolean terminate = false; + + private int count; + + private Throwable lastException; + + private RetryContext parent; + + public RetryContextSupport(RetryContext parent) { + super(); + this.parent = parent; + } + + public RetryContext getParent() { + return this.parent; + } + + public boolean isExhaustedOnly() { + return terminate; + } + + public void setExhaustedOnly() { + terminate = true; + } + + public int getRetryCount() { + return count; + } + + public Throwable getLastThrowable() { + return lastException; + } + + /** + * Set the exception for the public interface {@link RetryContext}, and + * also increment the retry count if the throwable is non-null.
+ * + * All {@link RetryPolicy} implementations should use this method when they + * register the throwable. It should only be called once per retry attempt + * because it increments a counter.
+ * + * Use of this method is not enforced by the framework - it is a service + * provider contract for authors of policies. + * + * @param throwable the exception that caused the current retry attempt to + * fail. + */ + public void registerThrowable(Throwable throwable) { + this.lastException = throwable; + if (throwable != null) + count++; + } + + @Override + public String toString() { + return String.format("[RetryContext: count=%d, lastException=%s, exhausted=%b]", count, lastException, terminate); + } + +} diff --git a/src/main/java/org/springframework/commons/retry/interceptor/MethodArgumentsKeyGenerator.java b/src/main/java/org/springframework/commons/retry/interceptor/MethodArgumentsKeyGenerator.java new file mode 100644 index 0000000..fd15b31 --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/interceptor/MethodArgumentsKeyGenerator.java @@ -0,0 +1,36 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ +package org.springframework.commons.retry.interceptor; + +/** + * Interface that allows method parameters to be identified and tagged by a + * unique key. + * + * @author Dave Syer + * + */ +public interface MethodArgumentsKeyGenerator { + + /** + * Get a unique identifier for the item that can be used to cache it between + * calls if necessary, and then identify it later. + * + * @param item the current item. + * @return a unique identifier. + */ + Object getKey(Object[] item); + +} diff --git a/src/main/java/org/springframework/commons/retry/interceptor/MethodInvocationRecoverer.java b/src/main/java/org/springframework/commons/retry/interceptor/MethodInvocationRecoverer.java new file mode 100644 index 0000000..376a6b9 --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/interceptor/MethodInvocationRecoverer.java @@ -0,0 +1,40 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry.interceptor; + + +/** + * Strategy interface for recovery action when processing of an item fails.
+ * + * @author Dave Syer + */ +public interface MethodInvocationRecoverer { + + /** + * Recover gracefully from an error. Clients can call this if processing of + * the item throws an unexpected exception. Caller can use the return value + * to decide whether to try more corrective action or perhaps throw an + * exception. + * + * @param args + * the arguments for the method invocation that failed. + * @param cause + * the cause of the failure that led to this recovery. + * @return the value to be returned to the caller + */ + T recover(Object[] args, Throwable cause); +} diff --git a/src/main/java/org/springframework/commons/retry/interceptor/NewMethodArgumentsIdentifier.java b/src/main/java/org/springframework/commons/retry/interceptor/NewMethodArgumentsIdentifier.java new file mode 100644 index 0000000..92b1f2b --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/interceptor/NewMethodArgumentsIdentifier.java @@ -0,0 +1,37 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry.interceptor; + +/** + * Strategy interface to distinguish new arguments from ones that have been + * processed before, e.g. by examining a message flag. + * + * @author Dave Syer + * + */ +public interface NewMethodArgumentsIdentifier { + + /** + * Inspect the arguments and determine if they have never been processed + * before. The safest choice when the answer is indeterminate is 'false'. + * + * @param args the current method arguments. + * @return true if the item is known to have never been processed before. + */ + boolean isNew(Object[] args); + +} diff --git a/src/main/java/org/springframework/commons/retry/interceptor/RetryOperationsInterceptor.java b/src/main/java/org/springframework/commons/retry/interceptor/RetryOperationsInterceptor.java new file mode 100644 index 0000000..377482f --- /dev/null +++ b/src/main/java/org/springframework/commons/retry/interceptor/RetryOperationsInterceptor.java @@ -0,0 +1,86 @@ +/* + * Copyright 2006-2007 the original author or authors. + * + * Licensed 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. + */ + +package org.springframework.commons.retry.interceptor; + +import org.aopalliance.intercept.MethodInterceptor; +import org.aopalliance.intercept.MethodInvocation; +import org.springframework.aop.ProxyMethodInvocation; +import org.springframework.commons.retry.RetryCallback; +import org.springframework.commons.retry.RetryContext; +import org.springframework.commons.retry.RetryOperations; +import org.springframework.commons.retry.support.RetryTemplate; +import org.springframework.util.Assert; + +/** + * A {@link MethodInterceptor} that can be used to automatically retry calls to + * a method on a service if it fails. The injected {@link RetryOperations} is + * used to control the number of retries. By default it will retry a fixed + * number of times, according to the defaults in {@link RetryTemplate}.
+ * + * Hint about transaction boundaries. If you want to retry a failed transaction + * you need to make sure that the transaction boundary is inside the retry, + * otherwise the successful attempt will roll back with the whole transaction. + * If the method being intercepted is also transactional, then use the ordering + * hints in the advice declarations to ensure that this one is before the + * transaction interceptor in the advice chain. + * + * @author Rob Harrop + * @author Dave Syer + */ +public class RetryOperationsInterceptor implements MethodInterceptor { + + private RetryOperations retryOperations = new RetryTemplate(); + + public void setRetryOperations(RetryOperations retryTemplate) { + Assert.notNull(retryTemplate, "'retryOperations' cannot be null."); + this.retryOperations = retryTemplate; + } + + public Object invoke(final MethodInvocation invocation) throws Throwable { + + return this.retryOperations.execute(new RetryCallback