Changeset 1725

Timestamp:

12/03/11 12:57:19 (6 months ago)

Author:

jharrop

Message:

Add some comments

Location:

trunk/docx4j/src/main/java/org/docx4j

Files:

• TraversalUtil.java (modified) (4 diffs)
• utils/CompoundTraversalUtilVisitorCallback.java (modified) (2 diffs)
• utils/SingleTraversalUtilVisitorCallback.java (modified) (1 diff)
• utils/TraversalUtilVisitor.java (modified) (1 diff)

trunk/docx4j/src/main/java/org/docx4j/TraversalUtil.java

@@ -122 +122 @@
                 /**
                  * Visits a node in pre order (before its children have been visited).
+
                  * 
                  * A node is visited only if all its parents have been traversed (
@@ -396 +397 @@
         }
         
-        public static void visit(WordprocessingMLPackage wmlPackage, boolean bodyOnly, TraversalUtilVisitor visitor) {
+        /** 
+         * Use this if there is only a single object type (eg just P's)
+         * you are interested in doing something with.  
+         * 
+         * This method allows you to traverse just the main document
+         * part, or also headers/footers, footnotes/endnotes, and comments
+         * as well. 
+         * 
+         * @param wmlPackage
+         * @param bodyOnly
+         * @param visitor
+         */
+        public static void visit(WordprocessingMLPackage wmlPackage, 
+                        boolean bodyOnly, TraversalUtilVisitor visitor) {
+                
                 if (visitor != null) {
                         visit(wmlPackage, bodyOnly, new SingleTraversalUtilVisitorCallback(visitor));
                 }
         }
+
+        /** 
+         * Use this if there is only a single object type (eg just P's)
+         * you are interested in doing something with.
+         * 
+         * This method is for traversing an arbitrary WML object (eg a table), as opposed to
+         * eg the main document part, or a header.
+         * 
+         * @param parent
+         * @param visitor
+         */
+        public static void visit(Object parent, TraversalUtilVisitor visitor) {
+                
+                if (visitor != null) {
+                        visit(parent, new SingleTraversalUtilVisitorCallback(visitor));
+                }
+        }
         
-        public static void visit(WordprocessingMLPackage wmlPackage, boolean bodyOnly, List<TraversalUtilVisitor> visitorList) {
-        CompoundTraversalUtilVisitorCallback callback = null;
+        /** 
+         * Use this if there is more than one object type (eg Tables and Paragraphs)
+         * you are interested in doing something with during the traversal.
+         * 
+         * This method allows you to traverse just the main document
+         * part, or also headers/footers, footnotes/endnotes, and comments
+         * as well. 
+         * 
+         * @param wmlPackage
+         * @param bodyOnly
+         * @param visitorList
+         */
+        public static void visit(WordprocessingMLPackage wmlPackage,
+                        boolean bodyOnly, List<TraversalUtilVisitor> visitorList) {
+                
+                CompoundTraversalUtilVisitorCallback callback = null;
                 if ((visitorList != null) && (!visitorList.isEmpty())) {
                         if (visitorList.size() > 1) {
-                                visit(wmlPackage, bodyOnly, new CompoundTraversalUtilVisitorCallback(visitorList));
-                        }
-                        else {
+                                visit(wmlPackage, bodyOnly,
+                                                new CompoundTraversalUtilVisitorCallback(visitorList));
+                        } else {
                                 visit(wmlPackage, bodyOnly, visitorList.get(0));
                         }
                 }
         }
-        
-        public static void visit(WordprocessingMLPackage wmlPackage, boolean bodyOnly, Callback callback) {
-        MainDocumentPart mainDocument = null;
-        RelationshipsPart relPart = null;
-        List<Relationship> relList = null;
-        List<Object> elementList = null;
+
+        /** 
+         * Use this if there is more than one object type (eg Tables and Paragraphs)
+         * you are interested in doing something with during the traversal.
+         * 
+         * This method is for traversing an arbitrary WML object (eg a table), as opposed to
+         * eg the main document part, or a header.
+         * 
+         * @param parent
+         * @param visitorList
+         */
+        public static void visit(Object parent,
+                        List<TraversalUtilVisitor> visitorList) {
+                
+                CompoundTraversalUtilVisitorCallback callback = null;
+                if ((visitorList != null) && (!visitorList.isEmpty())) {
+                        if (visitorList.size() > 1) {
+                                visit(parent, new CompoundTraversalUtilVisitorCallback(
+                                                visitorList));
+                        } else {
+                                visit(parent, visitorList.get(0));
+                        }
+                }
+        }
+
+        public static void visit(Object parent, Callback callback) {
+                
+                if ((parent != null) && (callback != null)) {
+                        callback.walkJAXBElements(parent);
+                }
+        }
+
+        public static void visit(WordprocessingMLPackage wmlPackage,
+                        boolean bodyOnly, Callback callback) {
+                
+                MainDocumentPart mainDocument = null;
+                RelationshipsPart relPart = null;
+                List<Relationship> relList = null;
+                List<Object> elementList = null;
+                
                 if ((wmlPackage != null) && (callback != null)) {
                         mainDocument = wmlPackage.getMainDocumentPart();
@@ -425 +505 @@
                                 relPart = mainDocument.getRelationshipsPart();
                                 relList = relPart.getRelationships().getRelationship();
-                                for (Relationship rs:relList) {
+                                for (Relationship rs : relList) {
                                         elementList = null;
                                         if (Namespaces.HEADER.equals(rs.getType())) {
-                                                elementList = ((HeaderPart)relPart.getPart(rs)).getJaxbElement().getEGBlockLevelElts();
-                                        }
-                                        else if (Namespaces.FOOTER.equals(rs.getType())) {
-                                                elementList = ((FooterPart)relPart.getPart(rs)).getJaxbElement().getEGBlockLevelElts();
-                                        }
-                                        else if (Namespaces.ENDNOTES.equals(rs.getType())) {
+                                                elementList = ((HeaderPart) relPart.getPart(rs))
+                                                                .getJaxbElement().getContent();
+                                        } else if (Namespaces.FOOTER.equals(rs.getType())) {
+                                                elementList = ((FooterPart) relPart.getPart(rs))
+                                                                .getJaxbElement().getContent();
+                                        } else if (Namespaces.ENDNOTES.equals(rs.getType())) {
                                                 elementList = new ArrayList();
-                                                for (CTFtnEdn endnote: ((EndnotesPart)relPart.getPart(rs)).getJaxbElement().getEndnote()) {
+                                                for (CTFtnEdn endnote : ((EndnotesPart) relPart
+                                                                .getPart(rs)).getJaxbElement().getEndnote()) {
                                                         elementList.addAll(endnote.getEGBlockLevelElts());
                                                 }
-                                        }
-                                        else if (Namespaces.FOOTNOTES.equals(rs.getType())) {
+                                        } else if (Namespaces.FOOTNOTES.equals(rs.getType())) {
                                                 elementList = new ArrayList();
-                                                for (CTFtnEdn footnote: ((FootnotesPart)relPart.getPart(rs)).getJaxbElement().getFootnote()) {
+                                                for (CTFtnEdn footnote : ((FootnotesPart) relPart
+                                                                .getPart(rs)).getJaxbElement().getFootnote()) {
                                                         elementList.addAll(footnote.getEGBlockLevelElts());
                                                 }
-                                        }
-                                        else if (Namespaces.COMMENTS.equals(rs.getType())) {
+                                        } else if (Namespaces.COMMENTS.equals(rs.getType())) {
                                                 elementList = new ArrayList();
-                                                for (Comment comment: ((CommentsPart)relPart.getPart(rs)).getJaxbElement().getComment()) {
+                                                for (Comment comment : ((CommentsPart) relPart
+                                                                .getPart(rs)).getJaxbElement().getComment()) {
                                                         elementList.addAll(comment.getEGBlockLevelElts());
                                                 }
                                         }
                                         if ((elementList != null) && (!elementList.isEmpty())) {
-                                                System.out.println("Processing target: " + rs.getTarget() + ", type: " + rs.getType());
+                                                System.out.println("Processing target: "
+                                                                + rs.getTarget() + ", type: " + rs.getType());
                                                 callback.walkJAXBElements(elementList);
                                         }
@@ -460 +542 @@
         }
         
-        public static void visit(Object parent, TraversalUtilVisitor visitor) {
-                if (visitor != null) {
-                        visit(parent, new SingleTraversalUtilVisitorCallback(visitor));
-                }
-        }
-        
-        public static void visit(Object parent, List<TraversalUtilVisitor> visitorList) {
-        CompoundTraversalUtilVisitorCallback callback = null;
-                if ((visitorList != null) && (!visitorList.isEmpty())) {
-                        if (visitorList.size() > 1) {
-                                visit(parent, new CompoundTraversalUtilVisitorCallback(visitorList));
-                        }
-                        else {
-                                visit(parent, visitorList.get(0));
-                        }
-                }
-        }
-        
-        public static void visit(Object parent, Callback callback) {
-                if ((parent != null) && (callback != null)) {
-                        callback.walkJAXBElements(parent);
-                }
-        }
-
         // private void describeDrawing( org.docx4j.wml.Drawing d) {
         //                      

trunk/docx4j/src/main/java/org/docx4j/utils/CompoundTraversalUtilVisitorCallback.java

@@ -6 +6 @@
 import java.util.Map;
 
-/** @author alberto */
-public class CompoundTraversalUtilVisitorCallback extends AbstractTraversalUtilVisitorCallback {
+/** 
+ * Use this if there is more than one object type (eg Tables and Paragraphs)
+ * you are interested in doing something with during the traversal.
+ * 
+ *  @author alberto */
+public class CompoundTraversalUtilVisitorCallback extends
+                AbstractTraversalUtilVisitorCallback {
+        
         Map<Class, List<TraversalUtilVisitor>> visitorMap = null;
-        
-        public CompoundTraversalUtilVisitorCallback(List<TraversalUtilVisitor> visitorList) {
+
+        public CompoundTraversalUtilVisitorCallback(
+                        List<TraversalUtilVisitor> visitorList) {
+                
                 visitorMap = setupTraversalVistorMap(visitorList);
+        }
+
+        protected Map<Class, List<TraversalUtilVisitor>> setupTraversalVistorMap(
+                        List<TraversalUtilVisitor> visitorList) {
                 
-        }
-        
-        protected Map<Class, List<TraversalUtilVisitor>> setupTraversalVistorMap(List<TraversalUtilVisitor> visitorList) {
-        Map<Class, List<TraversalUtilVisitor>> ret = new HashMap<Class, List<TraversalUtilVisitor>>();
-        Class visitorClass = null;
-        List<TraversalUtilVisitor> classVisitorList = null;
-                for (TraversalUtilVisitor visitor:visitorList) {
+                Map<Class, List<TraversalUtilVisitor>> ret = new HashMap<Class, List<TraversalUtilVisitor>>();
+                Class visitorClass = null;
+                List<TraversalUtilVisitor> classVisitorList = null;
+                for (TraversalUtilVisitor visitor : visitorList) {
                         visitorClass = findClassParameter(visitor.getClass());
                         if (visitorClass == null) {
-                                throw new IllegalArgumentException("Can't identify the parameter class of the visitor " + visitor.getClass().getName());
+                                throw new IllegalArgumentException(
+                                                "Can't identify the parameter class of the visitor "
+                                                                + visitor.getClass().getName());
                         }
                         classVisitorList = ret.get(visitorClass);
@@ -33 +44 @@
                 return ret;
         }
-        
+
         @Override
         protected List<Object> apply(Object child, Object parent, List siblings) {
-        List<TraversalUtilVisitor> classVisitorList = visitorMap.get(child.getClass());
+                
+                List<TraversalUtilVisitor> classVisitorList = visitorMap.get(child
+                                .getClass());
                 if (classVisitorList != null) {
-                        for (TraversalUtilVisitor visitor:classVisitorList) {
+                        for (TraversalUtilVisitor visitor : classVisitorList) {
                                 visitor.apply(child, parent, siblings);
                         }

trunk/docx4j/src/main/java/org/docx4j/utils/SingleTraversalUtilVisitorCallback.java

@@ -3 +3 @@
 import java.util.List;
 
-/** @author alberto */
+/** 
+ * Use this if there is only a single object type (eg just P's)
+ * you are interested in doing something with.
+ * 
+ * @author alberto */
 public class SingleTraversalUtilVisitorCallback extends AbstractTraversalUtilVisitorCallback {
+        
         protected TraversalUtilVisitor visitor = null;
         protected Class visitorClass = null;

trunk/docx4j/src/main/java/org/docx4j/utils/TraversalUtilVisitor.java

@@ -22 +22 @@
 import java.util.List;
 
-/* Doing this as a class instead of an interface ensures that it is 
- * part of the inheritance hierarchy.
+/**
  * 
+ * Extend this class to specify what should be done when a
+ * particular object (eg P or Table) is visited during the
+ * traversal.
+ *
  *  @author alberto
  */
 public abstract class TraversalUtilVisitor<T> {
+// Doing this as a class instead of an interface ensures that it is part of the inheritance hierarchy.
+        
         /**
          *