added Workbook.getName(String) method. Fixed javadoc on related methods

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

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

@@ -1292,23 +1292,31 @@ public class HSSFWorkbook extends POIDocument implements org.apache.poi.ss.userm
         return workbook;
     }
 
-    /** gets the total number of named ranges in the workboko
-     * @return number of named ranges
-     */
     public int getNumberOfNames(){
         int result = names.size();
         return result;
     }
     
-    /** gets the Named range
+    public HSSFName getName(String name) {
-     * @param index position of the named range
+        int nameIndex = getNameIndex(name);
-     * @return named range high level
+        if (nameIndex < 0) {
-     */
+            return null;
-    public HSSFName getNameAt(int index){
-        HSSFName result = (HSSFName) names.get(index);
-
-        return result;
         }
+        return (HSSFName) names.get(nameIndex);
+    }
+
+    public HSSFName getNameAt(int nameIndex) {
+        int nNames = names.size();
+        if (nNames < 1) {
+            throw new IllegalStateException("There are no defined names in this workbook");
+        }
+        if (nameIndex < 0 || nameIndex > nNames) {
+            throw new IllegalArgumentException("Specified name index " + nameIndex 
+                    + " is outside the allowable range (0.." + (nNames-1) + ").");
+        }
+        return (HSSFName) names.get(nameIndex);
+    }
+
     public NameRecord getNameRecord(int nameIndex) {
         return getWorkbook().getNameRecord(nameIndex);
     }
@@ -1411,34 +1419,19 @@ public class HSSFWorkbook extends POIDocument implements org.apache.poi.ss.userm
         return newName;
     }
 
-    /** gets the named range index by his name
+    public int getNameIndex(String name) {
-     * <i>Note:</i>Excel named ranges are case-insensitive and
-     * this method performs a case-insensitive search.
-     *
-     * @param name named range name
-     * @return named range index
-     */
-    public int getNameIndex(String name)
-    {
-        int retval = -1;
 
-        for (int k = 0; k < names.size(); k++)
+        for (int k = 0; k < names.size(); k++) {
-        {
             String nameName = getNameName(k);
 
-            if (nameName.equalsIgnoreCase(name))
+            if (nameName.equalsIgnoreCase(name)) {
-            {
+                return k;
-                retval = k;
-                break;
             }
         }
-        return retval;
+        return -1;
     }
 
 
-    /** remove the named range by his index
-     * @param index named range index (0 based)
-     */
     public void removeName(int index){
         names.remove(index);
         workbook.removeName(index);
@@ -1456,14 +1449,11 @@ public class HSSFWorkbook extends POIDocument implements org.apache.poi.ss.userm
     return formatter;
     }
 
-    /** remove the named range by his name
+
-     * @param name named range name
+    public void removeName(String name) {
-     */
-    public void removeName(String name){
         int index = getNameIndex(name);
 
         removeName(index);
-
     }
 
     public HSSFPalette getCustomPalette()

src/java/org/apache/poi/ss/usermodel/Workbook.java

@@ -274,48 +274,50 @@ public interface Workbook {
     void write(OutputStream stream) throws IOException;
 
     /**
-     * Gets the total number of named ranges in the workbook
+     * @return the total number of defined names in this workbook
-     *
-     * @return number of named ranges
      */
     int getNumberOfNames();
 
     /**
-     * Gets the Named range
+     * @param name the name of the defined name
-     *
+     * @return the defined name with the specified name. <code>null</code> if not found.
-     * @param index position of the named range (0-based)
-     * @return named range high level
      */
-    Name getNameAt(int index);
+    Name getName(String name);
+    /**
+     * @param nameIndex position of the named range (0-based)
+     * @return the defined name at the specified index
+     * @throws IllegalArgumentException if the supplied index is invalid
+     */
+    Name getNameAt(int nameIndex);
 
     /**
-     * Creates a new named range in this workbook
+     * Creates a new (uninitialised) defined name in this workbook
      *
-     * @return new named range object
+     * @return new defined name object
      */
     Name createName();
 
     /**
-     * Gets the named range index by his name
+     * Gets the defined name index by name<br/>
-      * <i>Note:</i>Excel named ranges are case-insensitive and
+     * <i>Note:</i> Excel defined names are case-insensitive and
      * this method performs a case-insensitive search.
      *
-      * @param name named range name
+     * @param name the name of the defined name
-      * @return named range index
+     * @return zero based index of the defined name. <tt>-1</tt> if not found.
      */
     int getNameIndex(String name);
 
     /**
-      * Remove the named range by his index
+     * Remove the defined name at the specified index
      *
      * @param index named range index (0 based)
      */
     void removeName(int index);
 
     /**
-     * Remove the named range by his name
+     * Remove a defined name by name
      *
-     * @param name named range name
+      * @param name the name of the defined name
      */
     void removeName(String name);
 

src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFWorkbook.java

@@ -417,11 +417,6 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Iterable<X
         return font;
     }
 
-    /**
-     * Create a new named range and add it to the workbook's names table
-     *
-     * @return named range high level
-     */
     public XSSFName createName() {
         XSSFName name = new XSSFName(CTDefinedName.Factory.newInstance(), this);
         namedRanges.add(name);
@@ -545,14 +540,24 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Iterable<X
         return stylesSource.getFontAt(idx);
     }
 
-    /**
+    public XSSFName getName(String name) {
-     * Gets the Named range at the given index number
+        int nameIndex = getNameIndex(name);
-     *
+        if (nameIndex < 0) {
-     * @param index position of the named range
+            return null;
-     * @return XSSFName at the index
+        }
-     */
+        return namedRanges.get(nameIndex);
-    public XSSFName getNameAt(int index) {
+    }
-        return namedRanges.get(index);
+
+    public XSSFName getNameAt(int nameIndex) {
+        int nNames = namedRanges.size();
+        if (nNames < 1) {
+            throw new IllegalStateException("There are no defined names in this workbook");
+        }
+        if (nameIndex < 0 || nameIndex > nNames) {
+            throw new IllegalArgumentException("Specified name index " + nameIndex 
+                    + " is outside the allowable range (0.." + (nNames-1) + ").");
+        }
+        return namedRanges.get(nameIndex);
     }
 
     /**
@@ -713,21 +718,10 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Iterable<X
         return getPackagePart().getContentType().equals(XSSFRelation.MACROS_WORKBOOK.getContentType());
     }
 
-    /**
-     * Removes the name by its index
-     *
-     * @param nameIndex 0-based index of the name to remove.
-     */
     public void removeName(int nameIndex) {
         namedRanges.remove(nameIndex);
     }
 
-    /**
-     * Remove the named range by its name
-     *
-     * @param name named range name
-     * @throws IllegalArgumentException if the name was not found
-     */
     public void removeName(String name) {
         for (int i = 0; i < namedRanges.size(); i++) {
             XSSFName nm = namedRanges.get(i);