Getting Started

There are several ways in which this library will allow you to create Excel files.

The generic way is:

				
// Get the factory
Java2ExcelDtdFactory factory = Java2ExcelDtdFactory.getInstance();
					
// Use the factory to get the instance to the configurer
Java2ExcelDtd java2ExcelDtd = factory. [...];
					
// Construct the ExcelWritter
ExcelWritter excelWritter = new ExcelWritter();
					
// Get your collection ready
Collection col = [...];
					
// Add the collection to the excel
// You can add as many of these as you want. Each one 
// will go to a different excel Sheet.
excelWritter.addReport(col, java2ExcelDtd);

// Finally, save the excel to a File or OutputStream
excelWritter.saveTo(new File("someExcel.xls"))

The major differences show up at the time of getting an instance of a Java2ExcelDtd.

Using only Xml config file

Using an xml file gives you the most flexible way of making you excel file, allowing you to configure things such as column titles. You have an xml example here.

					
// Get your xml file as input stream
InputStream yourXmlInputStream = [...];
					
// Parse it and make the config object
Java2ExcelDtd java2ExcelDtd = factory.readFromFile(yourXmlInputStream);

Without Xml config file

You can get a Java2ExcelDtd without needing to configure any xml file. This way, every property has to be read by reflection. 

					
// Define until which level the properties should be read
int includeExtraLevel = 1;
Java2ExcelDtd java2ExcelDtd = factory.defaultJava2ExcelDtd(includeExtraLevel);

The includeExtraLevel parameter is very important because it defines until which level the properties will be looked for.

Posible values are:

  • -1 - Will no scan any property at all
  • 0 - Will scan properties printable to excel only in the root level. In other words, only in the elements of the Collection
  • 1 - Will scan level 0 and will scan recursively every property that returns a value of a type different from java.lang.Class and java.util.Collection.
  • And so forth...

The defaultJava2ExcelDtd() method is overloaded. There are two more versions that allow you to set different java types to ignore while scanning recursively for properties.

Combining Xml and Reflection

The final aproach is to use an xml file that allows you to also scan properties by reflection.

You use the xml file as explained before, but in the xml file you set the parameter includeExtraLevel to the properties tag with a value greater than or equals to 0

In the java code, you must note that the readFromFile() method from the Java2ExcelDtdFactory is overloaded. There are two more versions that allow you to set different java types to ignore while scanning recursively for properties.

Example Xml file

The following is an example xml file that I use in one of the tests. It is commented pretty well enough, I think.

					
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE java2excel PUBLIC "-//epere4/DTD Java2Excel mapping file//EN"
	"http://java2excel.sourceforge.net/dtd/java2excel-mapping.dtd">
<java2excel>
	<!-- 
		This header is here just for future enhancements. Don't use it.
		You can even ommit the header if you want. Please note that future
		versions may not support any CDATA inside the header tags.
	-->
	<header> nothing for now </header>
	<body>
		<!-- 
		Setting an includeExtraLevel="1" makes the excel writer
		to scan (by reflection) all the properties in levels 1 and 0 of each element
		in the collection. The default value here is includeExtraLevel = "-1"
		which means no reflection scan at all.
		-->
		<properties includeExtraLevel="1">
			<!-- 
			expression is an ognl expression that will be applied to
			each element in the collection to obtain its value.
			In the road to getting the value some problems may arrise, 
			such as a property being inexistent or null. With 
			protectNullPointer="true" (which is the default value, by the way)
			all exception of this kind will be ignored and an empty cell
			will go to excel.
			-->
			<property expression="text" protectNullPointer="true">
				<description> This is a text property. </description>
			</property>
			<property expression="integerNumber" protectNullPointer="false"/>
			<property expression="date"/>
			<property expression="calendar"/>
			<property expression="boolValue"/>
			<!-- 
			If the title parameter is set, then the excel column will have
			that text as title. If parameter is ommited, then the 
			column name will be exactly what you put in expression.
			-->
			<property expression="internal.integerNumber"
				title="Interal Integer Number"/>
			<property expression="internal.date" title="ESTE ES NULL"/>
			<property expression="internal2.integerNumber"
				protectNullPointer="true"/>
			
		</properties>
	</body>
</java2excel>

The expression attributes are ognl expressions that are applied to each element in the collection.

For example, integerNumber will be traduced to something like elementInCollection.getIntegerNumber() (with elementInCollection being the name of the variable for each element in the collection, of course).

A more complex expresion like internal.integerNumber is equivalent to elementInCollection.getInternal().getIntegerNumber() . An exception could be thrown here if getInternal() returns null, for example. These kind of situations can be avoided with the parameter protectNullPointer="true"