more javadoc + clean-up from Dmitriy (bug 30311 att 21711)

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@641157 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/poi/hssf/record/aggregates/CFRecordsAggregate.java

@@ -35,16 +35,16 @@ import org.apache.poi.util.POILogger;
  * @author Dmitriy Kumshayev
  *
  */
-public class CFRecordsAggregate extends Record
+public final class CFRecordsAggregate extends Record
 {
-    public final static short sid = -2008;
+	public final static short sid = -2008; // not a real BIFF record
 
 	private static POILogger  log = POILogFactory.getLogger(CFRecordsAggregate.class);
 
 	private CFHeaderRecord header;
 
 	// List of CFRuleRecord objects
-	private List rules;
+	private final List rules;
 
 	public CFRecordsAggregate()
 	{
@@ -58,12 +58,13 @@ public class CFRecordsAggregate extends Record
 	 * @param offset - position of {@link CFHeaderRecord} object in the list of Record objects
 	 * @return CFRecordsAggregate object
 	 */
-    public static CFRecordsAggregate createCFAggregate(List recs, int offset)
+	public static CFRecordsAggregate createCFAggregate(List recs, int pOffset)
 	{
+
+		int offset = pOffset;
 		CFRecordsAggregate 	cfRecords  = new CFRecordsAggregate();
 		ArrayList 		records = new ArrayList(4);
 
-        int count = 0;
 		Record rec = ( Record ) recs.get(offset++);
 
 		if (rec.getSid() == CFHeaderRecord.sid)
@@ -206,8 +207,6 @@ public class CFRecordsAggregate extends Record
 		{
 			buffer.append(header.toString());
 		}
-		if( rules != null )
-		{
 		for(int i=0; i<rules.size(); i++)
 		{
 			CFRuleRecord cfRule = (CFRuleRecord)rules.get(i);
@@ -216,9 +215,7 @@ public class CFRecordsAggregate extends Record
 				buffer.append(cfRule.toString());
 			}
 		}
-		}
 		buffer.append("[/CF]\n");
 		return buffer.toString();
 	}
-	
 }

src/java/org/apache/poi/hssf/usermodel/HSSFConditionalFormatting.java

@@ -27,8 +27,14 @@ import org.apache.poi.hssf.util.Region;
 
 /**
  * HSSFConditionalFormatting class encapsulates all settings of Conditional Formatting. 
- * The class is not intended to be used explicitly except cases when there is a need 
+ * 
- * to make a copy HSSFConditionalFormatting settings for some reason. 
+ * The class can be used 
+ * 
+ * <UL>
+ * <LI>
+ * to make a copy HSSFConditionalFormatting settings.
+ * </LI>
+ *  
  * 
  * For example:
  * <PRE>
@@ -36,7 +42,15 @@ import org.apache.poi.hssf.util.Region;
  * newSheet.addConditionalFormatting(cf);
  * </PRE>
  * 
+ *  <LI>
+ *  or to modify existing Conditional Formatting settings (formatting regions and/or rules).
+ *  </LI>
+ *  </UL>
+ * 
+ * Use {@link HSSFSheet#getConditionalFormattingAt(int)} to get access to an instance of this class. 
+ * <P>
  * To create a new Conditional Formatting set use the following approach:
+ * 
  * <PRE>
  * // Create pattern with red background
  * HSSFPatternFormatting patternFormatting = new HSSFPatternFormatting();
@@ -70,23 +84,29 @@ import org.apache.poi.hssf.util.Region;
  * 
  * @author Dmitriy Kumshayev
  */
-public class HSSFConditionalFormatting
+public final class HSSFConditionalFormatting
 {
-	HSSFSheet sheet;
+	private final HSSFSheet sheet;
-	CFRecordsAggregate cfAggregate;
+	private final CFRecordsAggregate cfAggregate;
 
-	protected HSSFConditionalFormatting(HSSFSheet sheet)
+	HSSFConditionalFormatting(HSSFSheet sheet) {
-	{
+		this(sheet, new CFRecordsAggregate());
-		this.sheet = sheet;
-		this.cfAggregate = new CFRecordsAggregate();
 	}
 
-	protected HSSFConditionalFormatting(HSSFSheet sheet, CFRecordsAggregate cfAggregate)
+	HSSFConditionalFormatting(HSSFSheet sheet, CFRecordsAggregate cfAggregate)
 	{
+		if(sheet == null) {
+			throw new IllegalArgumentException("sheet must not be null");
+		}
+		if(cfAggregate == null) {
+			throw new IllegalArgumentException("cfAggregate must not be null");
+		}
 		this.sheet = sheet;
 		this.cfAggregate = cfAggregate;
 	}
-	
+	CFRecordsAggregate getCFRecordsAggregate() {
+		return cfAggregate;
+	}
 
 	public void setFormattingRegions(Region[] regions)
 	{
@@ -97,35 +117,65 @@ public class HSSFConditionalFormatting
 		}
 	}
 
+	/**
+	 * @return array of <tt>Region</tt>s. never <code>null</code>
+	 */
 	public Region[] getFormattingRegions()
 	{
 		CFHeaderRecord cfh = cfAggregate.getHeader();
 
 		List cellRanges = cfh.getCellRanges();
 
-		if (cellRanges != null)
-		{
 		return toRegionArray(cellRanges);
 	}
-		return null;
-	}
 
-	public void setConditionalFormat(int idx, HSSFConditionalFormattingRule cfRule)
+	/**
+	 * set a Conditional Formatting rule at position idx. 
+	 * Excel allows to create up to 3 Conditional Formatting rules.
+	 * This method can be useful to modify existing  Conditional Formatting rules.
+	 * 
+	 * @param idx position of the rule. Should be between 0 and 2.
+	 * @param cfRule - Conditional Formatting rule
+	 */
+	public void setRule(int idx, HSSFConditionalFormattingRule cfRule)
 	{
+	    if (idx < 0 || idx > 2) {
+	        throw new IllegalArgumentException("idx must be between 0 and 2 but was (" 
+	                + idx + ")");
+	    }
 		cfAggregate.getRules().set(idx, cfRule);
 	}
 
-	public void addConditionalFormat(HSSFConditionalFormattingRule cfRule)
+	/**
+	 * add a Conditional Formatting rule. 
+	 * Excel allows to create up to 3 Conditional Formatting rules.
+	 * @param cfRule - Conditional Formatting rule
+	 */
+	public void addRule(HSSFConditionalFormattingRule cfRule)
 	{
 		cfAggregate.getRules().add(cfRule);
 	}
 
-	public HSSFConditionalFormattingRule getConditionalFormat(int idx)
+	/**
+	 * get a Conditional Formatting rule at position idx. 
+	 * @param idx
+	 * @return a Conditional Formatting rule at position idx.
+	 */
+	public HSSFConditionalFormattingRule getRule(int idx)
 	{
 		CFRuleRecord ruleRecord = (CFRuleRecord)cfAggregate.getRules().get(idx);
 		return new HSSFConditionalFormattingRule(sheet.workbook, ruleRecord);
 	}
 
+	/**
+	 * @return number of Conditional Formatting rules.
+	 */
+	public int getNumbOfRules()
+	{
+		return cfAggregate.getRules().size();
+	}
+
+
 	/**
 	 * Do all possible cell merges between cells of the list so that:<br>
 	 * 	<li>if a cell range is completely inside of another cell range, it gets removed from the list 
@@ -236,11 +286,7 @@ public class HSSFConditionalFormatting
 	}
 
 	public String toString()
-	{
-		if(cfAggregate!=null)
 	{
 		return cfAggregate.toString();
 	}
-		return null;
-	}
 }

src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java

@@ -15,11 +15,6 @@
    limitations under the License.
 ==================================================================== */
 
-/*
- * HSSFSheet.java
- *
- * Created on September 30, 2001, 3:40 PM
- */
 package org.apache.poi.hssf.usermodel;
 
 import org.apache.poi.ddf.EscherRecord;
@@ -61,9 +56,7 @@ import java.awt.geom.AffineTransform;
  * @author  Jean-Pierre Paris (jean-pierre.paris at m4x dot org) (Just a little, too)
  * @author  Yegor Kozlov (yegor at apache.org) (Autosizing columns)
  */
-
+public final class HSSFSheet {
-public class HSSFSheet
-{
     private static final int DEBUG = POILogger.DEBUG;
 
     /* Constants for margins */
@@ -1927,9 +1920,9 @@ public class HSSFSheet
       */
      public int addConditionalFormatting( HSSFConditionalFormatting cf )
      {
-      	HSSFConditionalFormatting cfClone = new HSSFConditionalFormatting(this,cf.cfAggregate.cloneCFAggregate());
+         CFRecordsAggregate cfraClone = cf.getCFRecordsAggregate().cloneCFAggregate();
-      	cfClone.sheet=this;
+
-     	return sheet.addConditionalFormatting(cfClone.cfAggregate);
+         return sheet.addConditionalFormatting(cfraClone);
      }
 
      /**
@@ -1949,10 +1942,10 @@ public class HSSFSheet
          {
              for( int i=0; i!= cfRules.length; i++ )
              {
-     	    	cf.addConditionalFormat(cfRules[i]);
+                 cf.addRule(cfRules[i]);
              }
          }
-     	return sheet.addConditionalFormatting(cf.cfAggregate);
+         return sheet.addConditionalFormatting(cf.getCFRecordsAggregate());
      }
 
     /**
@@ -1987,5 +1980,4 @@ public class HSSFSheet
     {
         sheet.removeConditionalFormatting(index);
     }
-
 }