added javadoc and code refactoring

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

8 files changed, 85 insertions, 109 deletions

diff --git a/src/java/org/apache/poi/hssf/usermodel/HSSFComment.java b/src/java/org/apache/poi/hssf/usermodel/HSSFComment.java
index 8ae7edbe73..8f4795b9bc 100644
--- a/src/java/org/apache/poi/hssf/usermodel/HSSFComment.java
+++ b/src/java/org/apache/poi/hssf/usermodel/HSSFComment.java
@@ -233,14 +233,14 @@ public class HSSFComment extends HSSFTextbox implements Comment {
     public void setBackgroundImage(int pictureIndex){
         setPropertyValue(new EscherSimpleProperty( EscherProperties.FILL__PATTERNTEXTURE, false, true, pictureIndex));
         setPropertyValue(new EscherSimpleProperty( EscherProperties.FILL__FILLTYPE, false, false, FILL_TYPE_PICTURE));
-        EscherBSERecord bse = _patriarch.getSheet().getWorkbook().getWorkbook().getBSERecord(pictureIndex);
+        EscherBSERecord bse = getPatriarch().getSheet().getWorkbook().getWorkbook().getBSERecord(pictureIndex);
         bse.setRef(bse.getRef() + 1);
     }
     
     public void resetBackgroundImage(){
         EscherSimpleProperty property = getOptRecord().lookup(EscherProperties.FILL__PATTERNTEXTURE);
         if (null != property){
-            EscherBSERecord bse = _patriarch.getSheet().getWorkbook().getWorkbook().getBSERecord(property.getPropertyValue());
+            EscherBSERecord bse = getPatriarch().getSheet().getWorkbook().getWorkbook().getBSERecord(property.getPropertyValue());
             bse.setRef(bse.getRef() - 1);
             getOptRecord().removeEscherProperty(EscherProperties.FILL__PATTERNTEXTURE);
         }
diff --git a/src/java/org/apache/poi/hssf/usermodel/HSSFPatriarch.java b/src/java/org/apache/poi/hssf/usermodel/HSSFPatriarch.java
index 152762ba4f..233a798dc7 100644
--- a/src/java/org/apache/poi/hssf/usermodel/HSSFPatriarch.java
+++ b/src/java/org/apache/poi/hssf/usermodel/HSSFPatriarch.java
@@ -90,6 +90,10 @@ public final class HSSFPatriarch implements HSSFShapeContainer, Drawing {
         return newPatriarch;
     }
 
+    /**
+     * @param shape to be removed
+     * @return true of shape is removed
+     */
     public boolean removeShape(HSSFShape shape) {
         boolean  isRemoved = _mainSpgrContainer.removeChildRecord(shape.getEscherContainer());
         if (isRemoved){
@@ -225,7 +229,7 @@ public final class HSSFPatriarch implements HSSFShapeContainer, Drawing {
     }
 
     /**
-     * Returns a list of all shapes contained by the patriarch.
+     * Returns a unmodifiable list of all shapes contained by the patriarch.
      */
     public List<HSSFShape> getChildren() {
         return Collections.unmodifiableList(_shapes);
@@ -236,7 +240,7 @@ public final class HSSFPatriarch implements HSSFShapeContainer, Drawing {
      */
     @Internal
     public void addShape(HSSFShape shape) {
-        shape._patriarch = this;
+        shape.setPatriarch(this);
         _shapes.add(shape);
     }
 
@@ -331,18 +335,30 @@ public final class HSSFPatriarch implements HSSFShapeContainer, Drawing {
         return false;
     }
 
+    /**
+     * @return x coordinate of the left up corner
+     */
     public int getX1() {
         return _spgrRecord.getRectX1();
     }
 
+    /**
+     * @return y coordinate of the left up corner
+     */
     public int getY1() {
         return _spgrRecord.getRectY1();
     }
 
+    /**
+     * @return x coordinate of the right down corner
+     */
     public int getX2() {
         return _spgrRecord.getRectX2();
     }
 
+    /**
+     * @return y coordinate of the right down corner
+     */
     public int getY2() {
         return _spgrRecord.getRectY2();
     }
@@ -377,6 +393,9 @@ public final class HSSFPatriarch implements HSSFShapeContainer, Drawing {
     }
 
 
+    /**
+     * create shape tree from existing escher records tree
+     */
     void buildShapeTree() {
         EscherContainerRecord dgContainer = _boundAggregate.getEscherContainer();
         if (dgContainer == null) {
@@ -397,10 +416,10 @@ public final class HSSFPatriarch implements HSSFShapeContainer, Drawing {
 
     private void setFlipFlags(HSSFShape shape){
         EscherSpRecord sp = shape.getEscherContainer().getChildById(EscherSpRecord.RECORD_ID);
-        if (shape.anchor.isHorizontallyFlipped()) {
+        if (shape.getAnchor().isHorizontallyFlipped()) {
             sp.setFlags(sp.getFlags() | EscherSpRecord.FLAG_FLIPHORIZ);
         }
-        if (shape.anchor.isVerticallyFlipped()) {
+        if (shape.getAnchor().isVerticallyFlipped()) {
             sp.setFlags(sp.getFlags() | EscherSpRecord.FLAG_FLIPVERT);
         }
     }
diff --git a/src/java/org/apache/poi/hssf/usermodel/HSSFPicture.java b/src/java/org/apache/poi/hssf/usermodel/HSSFPicture.java
index faffa20f01..1f20d9f0fa 100644
--- a/src/java/org/apache/poi/hssf/usermodel/HSSFPicture.java
+++ b/src/java/org/apache/poi/hssf/usermodel/HSSFPicture.java
@@ -206,7 +206,7 @@ public class HSSFPicture extends HSSFSimpleShape implements Picture {
 
     private float getColumnWidthInPixels(int column){
 
-        int cw = _patriarch.getSheet().getColumnWidth(column);
+        int cw = getPatriarch().getSheet().getColumnWidth(column);
         float px = getPixelWidth(column);
 
         return cw/px;
@@ -214,18 +214,18 @@ public class HSSFPicture extends HSSFSimpleShape implements Picture {
 
     private float getRowHeightInPixels(int i){
 
-        HSSFRow row = _patriarch.getSheet().getRow(i);
+        HSSFRow row = getPatriarch().getSheet().getRow(i);
         float height;
         if(row != null) height = row.getHeight();
-        else height = _patriarch.getSheet().getDefaultRowHeight();
+        else height = getPatriarch().getSheet().getDefaultRowHeight();
 
         return height/PX_ROW;
     }
 
     private float getPixelWidth(int column){
 
-        int def = _patriarch.getSheet().getDefaultColumnWidth()*256;
-        int cw = _patriarch.getSheet().getColumnWidth(column);
+        int def = getPatriarch().getSheet().getDefaultColumnWidth()*256;
+        int cw = getPatriarch().getSheet().getColumnWidth(column);
 
         return cw == def ? PX_DEFAULT : PX_MODIFIED;
     }
@@ -236,7 +236,7 @@ public class HSSFPicture extends HSSFSimpleShape implements Picture {
      * @return image dimension
      */
     public Dimension getImageDimension(){
-        EscherBSERecord bse = _patriarch.getSheet()._book.getBSERecord(getPictureIndex());
+        EscherBSERecord bse = getPatriarch().getSheet()._book.getBSERecord(getPictureIndex());
         byte[] data = bse.getBlipRecord().getPicturedata();
         int type = bse.getBlipTypeWin32();
         return ImageUtils.getImageDimension(new ByteArrayInputStream(data), type);
@@ -248,7 +248,7 @@ public class HSSFPicture extends HSSFSimpleShape implements Picture {
      * @return picture data for this shape
      */
     public HSSFPictureData getPictureData(){
-        InternalWorkbook iwb = _patriarch.getSheet().getWorkbook().getWorkbook();
+        InternalWorkbook iwb = getPatriarch().getSheet().getWorkbook().getWorkbook();
     	EscherBlipRecord blipRecord = iwb.getBSERecord(getPictureIndex()).getBlipRecord();
     	return new HSSFPictureData(blipRecord);
     }
diff --git a/src/java/org/apache/poi/hssf/usermodel/HSSFShape.java b/src/java/org/apache/poi/hssf/usermodel/HSSFShape.java
index daceee09a2..f20239567f 100644
--- a/src/java/org/apache/poi/hssf/usermodel/HSSFShape.java
+++ b/src/java/org/apache/poi/hssf/usermodel/HSSFShape.java
@@ -54,9 +54,9 @@ public abstract class HSSFShape {
     public static final int LINESTYLE_DEFAULT = LINESTYLE_NONE;
 
     // TODO - make all these fields private
-    HSSFShape parent;
+    private HSSFShape parent;
     HSSFAnchor anchor;
-    HSSFPatriarch _patriarch;
+    private HSSFPatriarch _patriarch;
 
     private final EscherContainerRecord _escherContainer;
     private final ObjRecord _objRecord;
@@ -93,6 +93,12 @@ public abstract class HSSFShape {
 
     protected abstract ObjRecord createObjRecord();
 
+    /**
+     * remove escher container from the patriarch.escherAggregate
+     * remove obj, textObj and note records if it's necessary
+     * in case of ShapeGroup remove all contained shapes
+     * @param patriarch
+     */
     protected abstract void afterRemove(HSSFPatriarch patriarch);
 
     /**
@@ -379,4 +385,16 @@ public abstract class HSSFShape {
     }
 
     protected abstract HSSFShape cloneShape();
+
+    protected void setPatriarch(HSSFPatriarch _patriarch) {
+        this._patriarch = _patriarch;
+    }
+
+    public HSSFPatriarch getPatriarch() {
+        return _patriarch;
+    }
+
+    protected void setParent(HSSFShape parent) {
+        this.parent = parent;
+    }
 }
diff --git a/src/java/org/apache/poi/hssf/usermodel/HSSFShapeGroup.java b/src/java/org/apache/poi/hssf/usermodel/HSSFShapeGroup.java
index a80e5bb98c..9f60d6eae4 100644
--- a/src/java/org/apache/poi/hssf/usermodel/HSSFShapeGroup.java
+++ b/src/java/org/apache/poi/hssf/usermodel/HSSFShapeGroup.java
@@ -129,18 +129,18 @@ public class HSSFShapeGroup extends HSSFShape implements HSSFShapeContainer {
         for ( int i=0; i<shapes.size(); i++ ) {
             HSSFShape shape = shapes.get(i);
             removeShape(shape);
-            shape.afterRemove(_patriarch);
+            shape.afterRemove(getPatriarch());
         }
         shapes.clear();
     }
 
     private void onCreate(HSSFShape shape){
-        if(_patriarch != null){
+        if(getPatriarch() != null){
             EscherContainerRecord spContainer = shape.getEscherContainer();
-            int shapeId = _patriarch.newShapeId();
+            int shapeId = getPatriarch().newShapeId();
             shape.setShapeId(shapeId);
             getEscherContainer().addChildRecord(spContainer);
-            shape.afterInsert(_patriarch);
+            shape.afterInsert(getPatriarch());
             EscherSpRecord sp;
             if (shape instanceof HSSFShapeGroup){
                 sp = shape.getEscherContainer().getChildContainers().get(0).getChildById(EscherSpRecord.RECORD_ID);
@@ -159,16 +159,16 @@ public class HSSFShapeGroup extends HSSFShape implements HSSFShapeContainer {
      */
     public HSSFShapeGroup createGroup(HSSFChildAnchor anchor) {
         HSSFShapeGroup group = new HSSFShapeGroup(this, anchor);
-        group.parent = this;
-        group.anchor = anchor;
+        group.setParent(this);
+        group.setAnchor(anchor);
         shapes.add(group);
         onCreate(group);
         return group;
     }
 
     public void addShape(HSSFShape shape) {
-        shape._patriarch = this._patriarch;
-        shape.parent = this;
+        shape.setPatriarch(this.getPatriarch());
+        shape.setParent(this);
         shapes.add(shape);
     }
 
@@ -180,15 +180,15 @@ public class HSSFShapeGroup extends HSSFShape implements HSSFShapeContainer {
      */
     public HSSFSimpleShape createShape(HSSFChildAnchor anchor) {
         HSSFSimpleShape shape = new HSSFSimpleShape(this, anchor);
-        shape.parent = this;
-        shape.anchor = anchor;
+        shape.setParent(this);
+        shape.setAnchor(anchor);
         shapes.add(shape);
         onCreate(shape);
         EscherSpRecord sp = shape.getEscherContainer().getChildById(EscherSpRecord.RECORD_ID);
-        if (shape.anchor.isHorizontallyFlipped()){
+        if (shape.getAnchor().isHorizontallyFlipped()){
             sp.setFlags(sp.getFlags() | EscherSpRecord.FLAG_FLIPHORIZ);
         }
-        if (shape.anchor.isVerticallyFlipped()){
+        if (shape.getAnchor().isVerticallyFlipped()){
             sp.setFlags(sp.getFlags() | EscherSpRecord.FLAG_FLIPVERT);
         }
         return shape;
@@ -202,8 +202,8 @@ public class HSSFShapeGroup extends HSSFShape implements HSSFShapeContainer {
      */
     public HSSFTextbox createTextbox(HSSFChildAnchor anchor) {
         HSSFTextbox shape = new HSSFTextbox(this, anchor);
-        shape.parent = this;
-        shape.anchor = anchor;
+        shape.setParent(this);
+        shape.setAnchor(anchor);
         shapes.add(shape);
         onCreate(shape);
         return shape;
@@ -218,8 +218,8 @@ public class HSSFShapeGroup extends HSSFShape implements HSSFShapeContainer {
      */
     public HSSFPolygon createPolygon(HSSFChildAnchor anchor) {
         HSSFPolygon shape = new HSSFPolygon(this, anchor);
-        shape.parent = this;
-        shape.anchor = anchor;
+        shape.setParent(this);
+        shape.setAnchor(anchor);
         shapes.add(shape);
         onCreate(shape);
         return shape;
@@ -234,16 +234,16 @@ public class HSSFShapeGroup extends HSSFShape implements HSSFShapeContainer {
      */
     public HSSFPicture createPicture(HSSFChildAnchor anchor, int pictureIndex) {
         HSSFPicture shape = new HSSFPicture(this, anchor);
-        shape.parent = this;
-        shape.anchor = anchor;
+        shape.setParent(this);
+        shape.setAnchor(anchor);
         shape.setPictureIndex(pictureIndex);
         shapes.add(shape);
         onCreate(shape);
         EscherSpRecord sp = shape.getEscherContainer().getChildById(EscherSpRecord.RECORD_ID);
-        if (shape.anchor.isHorizontallyFlipped()){
+        if (shape.getAnchor().isHorizontallyFlipped()){
             sp.setFlags(sp.getFlags() | EscherSpRecord.FLAG_FLIPHORIZ);
         }
-        if (shape.anchor.isVerticallyFlipped()){
+        if (shape.getAnchor().isVerticallyFlipped()){
             sp.setFlags(sp.getFlags() | EscherSpRecord.FLAG_FLIPVERT);
         }
         return shape;
@@ -357,7 +357,7 @@ public class HSSFShapeGroup extends HSSFShape implements HSSFShapeContainer {
         }
 
         HSSFShapeGroup group = new HSSFShapeGroup(spgrContainer, obj);
-        group._patriarch = patriarch;
+        group.setPatriarch(patriarch);
 
         for (HSSFShape shape: getChildren()){
             HSSFShape newShape;
@@ -375,7 +375,7 @@ public class HSSFShapeGroup extends HSSFShape implements HSSFShapeContainer {
     public boolean removeShape(HSSFShape shape) {
         boolean  isRemoved = getEscherContainer().removeChildRecord(shape.getEscherContainer());
         if (isRemoved){
-            shape.afterRemove(this._patriarch);
+            shape.afterRemove(this.getPatriarch());
             shapes.remove(shape);
         }
         return isRemoved;
diff --git a/src/java/org/apache/poi/hssf/usermodel/drawing/ShapeTypes.java b/src/java/org/apache/poi/hssf/usermodel/HSSFShapeTypes.java
index 3391130bd0..d72b4003d1 100644
--- a/src/java/org/apache/poi/hssf/usermodel/drawing/ShapeTypes.java
+++ b/src/java/org/apache/poi/hssf/usermodel/HSSFShapeTypes.java
@@ -15,9 +15,9 @@
    limitations under the License.
 ==================================================================== */
 
-package org.apache.poi.hssf.usermodel.drawing;
+package org.apache.poi.hssf.usermodel;
 
-public interface ShapeTypes {
+public interface HSSFShapeTypes {
     public static final int NotPrimitive = 0;
     public static final int Rectangle = 1;
     public static final int RoundRectangle = 2;
diff --git a/src/java/org/apache/poi/hssf/usermodel/HSSFSimpleShape.java b/src/java/org/apache/poi/hssf/usermodel/HSSFSimpleShape.java
index 3f14ecdf4e..ffbcec50e6 100644
--- a/src/java/org/apache/poi/hssf/usermodel/HSSFSimpleShape.java
+++ b/src/java/org/apache/poi/hssf/usermodel/HSSFSimpleShape.java
@@ -19,7 +19,6 @@ package org.apache.poi.hssf.usermodel;
 
 import org.apache.poi.ddf.*;
 import org.apache.poi.hssf.record.*;
-import org.apache.poi.hssf.usermodel.drawing.ShapeTypes;
 import org.apache.poi.ss.usermodel.RichTextString;
 
 /**
@@ -32,14 +31,14 @@ public class HSSFSimpleShape extends HSSFShape
     // The commented out ones haven't been tested yet or aren't supported
     // by HSSFSimpleShape.
 
-    public final static short       OBJECT_TYPE_LINE               = ShapeTypes.Line;
-    public final static short       OBJECT_TYPE_RECTANGLE          = ShapeTypes.Rectangle;
-    public final static short       OBJECT_TYPE_OVAL               = ShapeTypes.Ellipse;
-    public final static short       OBJECT_TYPE_ARC                = ShapeTypes.Arc;
+    public final static short       OBJECT_TYPE_LINE               = HSSFShapeTypes.Line;
+    public final static short       OBJECT_TYPE_RECTANGLE          = HSSFShapeTypes.Rectangle;
+    public final static short       OBJECT_TYPE_OVAL               = HSSFShapeTypes.Ellipse;
+    public final static short       OBJECT_TYPE_ARC                = HSSFShapeTypes.Arc;
     //    public final static short       OBJECT_TYPE_CHART              = 5;
 //    public final static short       OBJECT_TYPE_TEXT               = 6;
 //    public final static short       OBJECT_TYPE_BUTTON             = 7;
-    public final static short       OBJECT_TYPE_PICTURE            = ShapeTypes.PictureFrame;
+    public final static short       OBJECT_TYPE_PICTURE            = HSSFShapeTypes.PictureFrame;
 
 //    public final static short       OBJECT_TYPE_POLYGON            = 9;
 //    public final static short       OBJECT_TYPE_CHECKBOX           = 11;
@@ -51,8 +50,8 @@ public class HSSFSimpleShape extends HSSFShape
 //    public final static short       OBJECT_TYPE_SCROLL_BAR         = 17;
 //    public final static short       OBJECT_TYPE_LIST_BOX           = 18;
 //    public final static short       OBJECT_TYPE_GROUP_BOX          = 19;
-    public final static short       OBJECT_TYPE_COMBO_BOX          = ShapeTypes.HostControl;
-    public final static short       OBJECT_TYPE_COMMENT            = ShapeTypes.TextBox;
+    public final static short       OBJECT_TYPE_COMBO_BOX          = HSSFShapeTypes.HostControl;
+    public final static short       OBJECT_TYPE_COMMENT            = HSSFShapeTypes.TextBox;
     public final static short       OBJECT_TYPE_MICROSOFT_OFFICE_DRAWING = 30;
 
     public final static int WRAP_SQUARE = 0;
@@ -124,7 +123,7 @@ public class HSSFSimpleShape extends HSSFShape
 
         spContainer.addChildRecord(sp);
         spContainer.addChildRecord(optRecord);
-        spContainer.addChildRecord(anchor.getEscherAnchor());
+        spContainer.addChildRecord(getAnchor().getEscherAnchor());
         spContainer.addChildRecord(clientData);
         spContainer.addChildRecord(escherTextbox);
         return spContainer;
@@ -226,7 +225,7 @@ public class HSSFSimpleShape extends HSSFShape
     }
 
     /**
-     * @see org.apache.poi.hssf.usermodel.drawing.ShapeTypes
+     * @see HSSFShapeTypes
      * @param value - shapeType
      */
     public void setShapeType(int value){
diff --git a/src/java/org/apache/poi/hssf/usermodel/drawing/HSSFShapeType.java b/src/java/org/apache/poi/hssf/usermodel/drawing/HSSFShapeType.java
deleted file mode 100644
index 14dacc6a22..0000000000
--- a/src/java/org/apache/poi/hssf/usermodel/drawing/HSSFShapeType.java
+++ /dev/null
@@ -1,60 +0,0 @@
-/* ====================================================================

-   Licensed to the Apache Software Foundation (ASF) under one or more

-   contributor license agreements.  See the NOTICE file distributed with

-   this work for additional information regarding copyright ownership.

-   The ASF licenses this file to You 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.apache.poi.hssf.usermodel.drawing;

-

-import org.apache.poi.hssf.record.EscherAggregate;

-import org.apache.poi.hssf.usermodel.HSSFPicture;

-import org.apache.poi.hssf.usermodel.HSSFSimpleShape;

-import org.apache.poi.hssf.usermodel.HSSFTextbox;

-

-/**

- * @author Evgeniy Berlog

- * date: 08.06.12

- */

-public enum HSSFShapeType {

-    NOT_PRIMITIVE((short)0x0, null, (short)0),

-    RECTANGLE((short)0x1, HSSFSimpleShape.class, HSSFSimpleShape.OBJECT_TYPE_RECTANGLE),

-    PICTURE((short)0x004B, HSSFPicture.class, HSSFSimpleShape.OBJECT_TYPE_PICTURE),

-    LINE((short)0x14, HSSFSimpleShape.class, HSSFSimpleShape.OBJECT_TYPE_LINE),

-    OVAL(EscherAggregate.ST_ELLIPSE, HSSFSimpleShape.class, HSSFSimpleShape.OBJECT_TYPE_OVAL),

-    ARC(EscherAggregate.ST_ARC, HSSFSimpleShape.class, HSSFSimpleShape.OBJECT_TYPE_ARC),

-    TEXT((short)202, HSSFTextbox.class, HSSFTextbox.OBJECT_TYPE_TEXT),

-    ROUND_RECTANGLE((short)0x2, null, null);

-

-    private Short type;

-    private Class shape;

-    private Short objectType;

-

-    private HSSFShapeType(Short type, Class shape, Short objectType) {

-        this.type = type;

-        this.shape = shape;

-        this.objectType = objectType;

-    }

-

-    public Short getType() {

-        return type;

-    }

-

-    public Class getShape() {

-        return shape;

-    }

-

-    public Short getObjectType() {

-        return objectType;

-    }

-}