The retriever chain builders stepFurther method is more safe to use

java/com.sap.sse.datamining/src/com/sap/sse/datamining/DataRetrieverChainBuilder.java

@@ -20,6 +20,8 @@ public interface DataRetrieverChainBuilder<DataSourceType> {
     
     /**
      * Steps to the next data retriever in the chain.
+     * 
+     * @throws IllegalStateException if {@link #canStepFurther()} would return <code>false</code>.
      */
     public DataRetrieverChainBuilder<DataSourceType> stepFurther();
 

java/com.sap.sse.datamining/src/com/sap/sse/datamining/impl/SimpleDataRetrieverChainBuilder.java

@@ -58,6 +58,10 @@ public class SimpleDataRetrieverChainBuilder<DataSourceType> implements DataRetr
 
     @Override
     public DataRetrieverChainBuilder<DataSourceType> stepFurther() {
+        if (!canStepFurther()) {
+            throw new IllegalStateException("The builder can't step any further");
+        }
+        
         currentRetrieverTypeIndex++;
         return this;
     }
@@ -65,7 +69,7 @@ public class SimpleDataRetrieverChainBuilder<DataSourceType> implements DataRetr
     @Override
     public DataRetrieverChainBuilder<DataSourceType> setFilter(FilterCriterion<?> filter) {
         if (!hasBeenInitialized()) {
-            throw new IllegalStateException();
+            throw new IllegalStateException("The builder hasn't been initialized");
         }
         
         if (!filter.getElementType().isAssignableFrom(getCurrentRetrievedDataType())) {
@@ -80,7 +84,7 @@ public class SimpleDataRetrieverChainBuilder<DataSourceType> implements DataRetr
     @Override
     public DataRetrieverChainBuilder<DataSourceType> addResultReceiver(Processor<?, ?> resultReceiver) {
         if (!hasBeenInitialized()) {
-            throw new IllegalStateException();
+            throw new IllegalStateException("The builder hasn't been initialized");
         }
         
         if (!resultReceiver.getInputType().isAssignableFrom(getCurrentRetrievedDataType())) {
@@ -98,7 +102,7 @@ public class SimpleDataRetrieverChainBuilder<DataSourceType> implements DataRetr
     @Override
     public Class<?> getCurrentRetrievedDataType() {
         if (!hasBeenInitialized()) {
-            throw new IllegalStateException();
+            throw new IllegalStateException("The builder hasn't been initialized");
         }
         
         return dataRetrieverTypesWithInformation.get(currentRetrieverTypeIndex).getRetrievedDataType();
@@ -107,7 +111,7 @@ public class SimpleDataRetrieverChainBuilder<DataSourceType> implements DataRetr
     @Override
     public int getCurrentRetrieverLevel() {
         if (!hasBeenInitialized()) {
-            throw new IllegalStateException();
+            throw new IllegalStateException("The builder hasn't been initialized");
         }
         
         return currentRetrieverTypeIndex;
@@ -117,7 +121,7 @@ public class SimpleDataRetrieverChainBuilder<DataSourceType> implements DataRetr
     @Override
     public Processor<DataSourceType, ?> build() {
         if (!hasBeenInitialized()) {
-            throw new IllegalStateException();
+            throw new IllegalStateException("The builder hasn't been initialized");
         }
         
         Processor<?, ?> firstRetriever = null;

java/com.sap.sse.datamining/src/com/sap/sse/datamining/impl/SimpleDataRetrieverChainDefinition.java

@@ -64,7 +64,7 @@ public class SimpleDataRetrieverChainDefinition<DataSourceType, DataType> implem
     public <ResultType> void startWith(Class<? extends Processor<DataSourceType, ResultType>> retrieverType,
                                        Class<ResultType> retrievedDataType, String retrievedDataTypeMessageKey) {
         if (isInitialized()) {
-            throw new UnsupportedOperationException("This retriever chain definition already has been started with '"
+            throw new IllegalStateException("This retriever chain definition already has been started with '"
                                                     + dataRetrieverTypesWithInformation.get(0).getRetrieverType().getSimpleName() + "'");
         }
         checkThatRetrieverHasUsableConstructor(retrieverType);
@@ -83,10 +83,10 @@ public class SimpleDataRetrieverChainDefinition<DataSourceType, DataType> implem
             Class<? extends Processor<NextInputType, NextResultType>> nextRetrieverType,
             Class<NextResultType> retrievedDataType, String retrievedDataTypeMessageKey) {
         if (!isInitialized()) {
-            throw new UnsupportedOperationException("This retriever chain definition hasn't been started yet");
+            throw new IllegalStateException("This retriever chain definition hasn't been started yet");
         }
         if (isComplete) {
-            throw new UnsupportedOperationException("This retriever chain definition is already complete");
+            throw new IllegalStateException("This retriever chain definition is already complete");
         }
         DataRetrieverTypeWithInformation<?, ?> dataRetrieverTypeWithInformation = dataRetrieverTypesWithInformation.get(dataRetrieverTypesWithInformation.size() - 1);
         @SuppressWarnings("unchecked")
@@ -129,7 +129,7 @@ public class SimpleDataRetrieverChainDefinition<DataSourceType, DataType> implem
     @Override
     public DataRetrieverChainBuilder<DataSourceType> startBuilding(ExecutorService executor) {
         if (!isComplete) {
-            throw new UnsupportedOperationException("This retriever chain definition hasn't been completed yet");
+            throw new IllegalStateException("This retriever chain definition hasn't been completed yet");
         }
         
         return new SimpleDataRetrieverChainBuilder<>(executor, dataRetrieverTypesWithInformation);

wiki/data-mining-architecture.md

@@ -87,6 +87,7 @@ Concrete data retriever chain instances can be constructed with a `DataRetriever
 * The method `stepFurther` iterates over the retriever chain and sets the next retrieval processor as the one to modify.
 	* Is similar to the `next` method of `Iterator`.
 	* Initializes the builder, which is necessary to call the modifying methods.
+	* Throws an exception, if the builder can't step any further.
 * The method `canStepFurther` returns `true`, if `stepFurther` can be called at least once more.
 	* Is similar to the `hasNext` method of `Iterator`