整理第六章的英文原版到MD

Author: renfufei

06_ItemReaders_ItemWriters/613.md

@@ -0,0 +1,4 @@
+# 6.13 Creating Custom ItemReaders and ItemWriters #
+
+
+So far in this chapter the basic contracts that exist for reading and writing in Spring Batch and some common implementations have been discussed. However, these are all fairly generic, and there are many potential scenarios that may not be covered by out of the box implementations. This section will show, using a simple example, how to create a custom *ItemReader* and *ItemWriter* implementation and implement their contracts correctly. The *ItemReader* will also implement *ItemStream*, in order to illustrate how to make a reader or writer restartable.

06_ItemReaders_ItemWriters/613_1.md

@@ -0,0 +1,99 @@
+## 6.13.1 Custom ItemReader Example ##
+
+For the purpose of this example, a simple *ItemReader* implementation that reads from a provided list will be created. We'll start out by implementing the most basic contract of *ItemReader*, read:
+
+	public class CustomItemReader<T> implements ItemReader<T>{
+	
+	    List<T> items;
+	
+	    public CustomItemReader(List<T> items) {
+	        this.items = items;
+	    }
+	
+	    public T read() throws Exception, UnexpectedInputException,
+	       NoWorkFoundException, ParseException {
+	
+	        if (!items.isEmpty()) {
+	            return items.remove(0);
+	        }
+	        return null;
+	    }
+	}
+
+This very simple class takes a list of items, and returns them one at a time, removing each from the list. When the list is empty, it returns null, thus satisfying the most basic requirements of an *ItemReader*, as illustrated below:
+
+	List<String> items = new ArrayList<String>();
+	items.add("1");
+	items.add("2");
+	items.add("3");
+	
+	ItemReader itemReader = new CustomItemReader<String>(items);
+	assertEquals("1", itemReader.read());
+	assertEquals("2", itemReader.read());
+	assertEquals("3", itemReader.read());
+	assertNull(itemReader.read());
+
+
+**Making the *ItemReader* Restartable**
+
+The final challenge now is to make the *ItemReader* restartable. Currently, if the power goes out, and processing begins again, the *ItemReader* must start at the beginning. This is actually valid in many scenarios, but it is sometimes preferable that a batch job starts where it left off. The key discriminant is often whether the reader is stateful or stateless. A stateless reader does not need to worry about restartability, but a stateful one has to try and reconstitute its last known state on restart. For this reason, we recommend that you keep custom readers stateless if possible, so you don't have to worry about restartability.
+
+If you do need to store state, then the ItemStream interface should be used:
+
+	public class CustomItemReader<T> implements ItemReader<T>, ItemStream {
+	
+	    List<T> items;
+	    int currentIndex = 0;
+	    private static final String CURRENT_INDEX = "current.index";
+	
+	    public CustomItemReader(List<T> items) {
+	        this.items = items;
+	    }
+	
+	    public T read() throws Exception, UnexpectedInputException,
+	        ParseException {
+	
+	        if (currentIndex < items.size()) {
+	            return items.get(currentIndex++);
+	        }
+	
+	        return null;
+	    }
+	
+	    public void open(ExecutionContext executionContext) throws ItemStreamException {
+	        if(executionContext.containsKey(CURRENT_INDEX)){
+	            currentIndex = new Long(executionContext.getLong(CURRENT_INDEX)).intValue();
+	        }
+	        else{
+	            currentIndex = 0;
+	        }
+	    }
+	
+	    public void update(ExecutionContext executionContext) throws ItemStreamException {
+	        executionContext.putLong(CURRENT_INDEX, new Long(currentIndex).longValue());
+	    }
+	
+	    public void close() throws ItemStreamException {}
+	}
+
+On each call to the *ItemStream* update method, the current index of the *ItemReader* will be stored in the provided *ExecutionContext* with a key of 'current.index'. When the *ItemStream* open method is called, the *ExecutionContext* is checked to see if it contains an entry with that key. If the key is found, then the current index is moved to that location. This is a fairly trivial example, but it still meets the general contract:
+
+	ExecutionContext executionContext = new ExecutionContext();
+	((ItemStream)itemReader).open(executionContext);
+	assertEquals("1", itemReader.read());
+	((ItemStream)itemReader).update(executionContext);
+	
+	List<String> items = new ArrayList<String>();
+	items.add("1");
+	items.add("2");
+	items.add("3");
+	itemReader = new CustomItemReader<String>(items);
+	
+	((ItemStream)itemReader).open(executionContext);
+	assertEquals("2", itemReader.read());
+
+
+Most ItemReaders have much more sophisticated restart logic. The *JdbcCursorItemReader*, for example, stores the row id of the last processed row in the Cursor.
+
+It is also worth noting that the key used within the *ExecutionContext* should not be trivial. That is because the same *ExecutionContext* is used for all *ItemStreams* within a *Step*. In most cases, simply prepending the key with the class name should be enough to guarantee uniqueness. However, in the rare cases where two of the same type of *ItemStream* are used in the same step (which can happen if two files are need for output) then a more unique name will be needed. For this reason, many of the Spring Batch *ItemReader* and ItemWriter implementations have a *setName()* property that allows this key name to be overridden.
+

06_ItemReaders_ItemWriters/613_2.md

@@ -0,0 +1,22 @@
+## 6.13.2 Custom ItemWriter Example ##
+
+Implementing a Custom *ItemWriter* is similar in many ways to the *ItemReader* example above, but differs in enough ways as to warrant its own example. However, adding restartability is essentially the same, so it won't be covered in this example. As with the *ItemReader* example, a *List* will be used in order to keep the example as simple as possible:
+
+	public class CustomItemWriter<T> implements ItemWriter<T> {
+	
+	    List<T> output = TransactionAwareProxyFactory.createTransactionalList();
+	
+	    public void write(List<? extends T> items) throws Exception {
+	        output.addAll(items);
+	    }
+	
+	    public List<T> getOutput() {
+	        return output;
+	    }
+	}
+
+**Making the *ItemWriter* Restartable**
+
+To make the *ItemWriter* restartable we would follow the same process as for the *ItemReader*, adding and implementing the *ItemStream* interface to synchronize the execution context. In the example we might have to count the number of items processed and add that as a footer record. If we needed to do that, we could implement *ItemStream* in our *ItemWriter* so that the counter was reconstituted from the execution context if the stream was re-opened.
+
+In many realistic cases, custom ItemWriters also delegate to another writer that itself is restartable (e.g. when writing to a file), or else it writes to a transactional resource so doesn't need to be restartable because it is stateless. When you have a stateful writer you should probably also be sure to implement *ItemStream* as well as *ItemWriter*. Remember also that the client of the writer needs to be aware of the *ItemStream*, so you may need to register it as a stream in the configuration xml.

06_ItemReaders_ItemWriters/66.md

@@ -0,0 +1,3 @@
+6.6 Flat Files
+
+One of the most common mechanisms for interchanging bulk data has always been the flat file. Unlike XML, which has an agreed upon standard for defining how it is structured (XSD), anyone reading a flat file must understand ahead of time exactly how the file is structured. In general, all flat files fall into two types: Delimited and Fixed Length. Delimited files are those in which fields are separated by a delimiter, such as a comma. Fixed Length files have fields that are a set length.

06_ItemReaders_ItemWriters/66_1.md

@@ -0,0 +1,11 @@
+## 6.6.1 The FieldSet ##
+
+When working with flat files in Spring Batch, regardless of whether it is for input or output, one of the most important classes is the *FieldSet*. Many architectures and libraries contain abstractions for helping you read in from a file, but they usually return a String or an array of Strings. This really only gets you halfway there. A *FieldSet* is Spring Batch’s abstraction for enabling the binding of fields from a file resource. It allows developers to work with file input in much the same way as they would work with database input. A *FieldSet* is conceptually very similar to a Jdbc *ResultSet*. FieldSets only require one argument, a *String* array of tokens. Optionally, you can also configure in the names of the fields so that the fields may be accessed either by index or name as patterned after *ResultSet*:
+
+	String[] tokens = new String[]{"foo", "1", "true"};
+	FieldSet fs = new DefaultFieldSet(tokens);
+	String name = fs.readString(0);
+	int value = fs.readInt(1);
+	boolean booleanValue = fs.readBoolean(2);
+
+There are many more options on the *FieldSet* interface, such as *Date*, long, *BigDecimal*, etc. The biggest advantage of the FieldSet is that it provides consistent parsing of flat file input. Rather than each batch job parsing differently in potentially unexpected ways, it can be consistent, both when handling errors caused by a format exception, or when doing simple data conversions.