Package org.apache.poi.xssf.usermodel

Class XSSFName

java.lang.Object
org.apache.poi.xssf.usermodel.XSSFName
All Implemented Interfaces:
Name
public final class XSSFName extends Object implements Name
Represents a defined named range in a SpreadsheetML workbook.

Defined names are descriptive text that is used to represents a cell, range of cells, formula, or constant value. Use easy-to-understand names, such as Products, to refer to hard to understand ranges, such as Sales!C20:C30.

Example: 

   XSSFWorkbook wb = new XSSFWorkbook();
   XSSFSheet sh = wb.createSheet("Sheet1");

   //applies to the entire workbook
   XSSFName name1 = wb.createName();
   name1.setNameName("FMLA");
   name1.setRefersToFormula("Sheet1!$B$3");

   //applies to Sheet1
   XSSFName name2 = wb.createName();
   name2.setNameName("SheetLevelName");
   name2.setComment("This name is scoped to Sheet1");
   name2.setLocalSheetId(0);
   name2.setRefersToFormula("Sheet1!$B$3");

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    BUILTIN_CONSOLIDATE_AREA
    A built-in defined name that refers to a consolidation area
    static final String
    BUILTIN_CRITERIA
    A built-in defined name that refers to a range containing the criteria values to be used in applying an advanced filter to a range of data
    static final String
    BUILTIN_DATABASE
    A built-in defined name that specified that the range specified is from a database data source
    static final String
    BUILTIN_EXTRACT
    this defined name refers to the range containing the filtered output values resulting from applying an advanced filter criteria to a source range
    static final String
    BUILTIN_FILTER_DB
    Can be one of the following this defined name refers to a range to which an advanced filter has been applied.
    static final String
    BUILTIN_PRINT_AREA
    A built-in defined name that specifies the workbook's print area
    static final String
    BUILTIN_PRINT_TITLE
    A built-in defined name that specifies the row(s) or column(s) to repeat at the top of each printed page.
    static final String
    BUILTIN_SHEET_TITLE
    A built-in defined name that refers to a sheet title.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    equals(Object o)
    Compares this name to the specified object.
    String
    getComment()
    Returns the comment the user provided when the name was created.
    boolean
    getFunction()
    Indicates that the defined name refers to a user-defined function.
    int
    getFunctionGroupId()
    Returns the function group index if the defined name refers to a function.
    String
    getNameName()
    Returns the name that will appear in the user interface for the defined name.
    String
    getRefersToFormula()
    Returns the formula that the name is defined to refer to.
    int
    getSheetIndex()
    Returns the sheet index this name applies to.
    String
    getSheetName()
    Get the sheets name which this named range is referenced to
    int
    hashCode()
     
    boolean
    isDeleted()
    Checks if this name points to a cell that no longer exists
    boolean
    isFunctionName()
    Is the name refers to a user-defined function ?
    boolean
    isHidden()
    Checks if this name is hidden, eg one of the built-in Excel internal names
    void
    setComment(String comment)
    Specifies the comment the user provided when the name was created.
    void
    setFunction(boolean value)
    Indicates that the defined name refers to a user-defined function.
    void
    setFunctionGroupId(int functionGroupId)
    Specifies the function group index if the defined name refers to a function.
    void
    setNameName(String name)
    Sets the name that will appear in the user interface for the defined name.
    void
    setRefersToFormula(String formulaText)
    Sets the formula that the name is defined to refer to.
    void
    setSheetIndex(int index)
    Tell Excel that this name applies to the worksheet with the specified index instead of the entire workbook.

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • BUILTIN_PRINT_AREA

      public static final String BUILTIN_PRINT_AREA
      A built-in defined name that specifies the workbook's print area
      See Also:

    • BUILTIN_PRINT_TITLE

      public static final String BUILTIN_PRINT_TITLE
      A built-in defined name that specifies the row(s) or column(s) to repeat at the top of each printed page.
      See Also:

    • BUILTIN_CRITERIA

      public static final String BUILTIN_CRITERIA
      A built-in defined name that refers to a range containing the criteria values to be used in applying an advanced filter to a range of data
      See Also:

    • BUILTIN_EXTRACT

      public static final String BUILTIN_EXTRACT
      this defined name refers to the range containing the filtered output values resulting from applying an advanced filter criteria to a source range
      See Also:

    • BUILTIN_FILTER_DB

      public static final String BUILTIN_FILTER_DB
      Can be one of the following
      • this defined name refers to a range to which an advanced filter has been applied. This represents the source data range, unfiltered.
      • This defined name refers to a range to which an AutoFilter has been applied
      See Also:

    • BUILTIN_CONSOLIDATE_AREA

      public static final String BUILTIN_CONSOLIDATE_AREA
      A built-in defined name that refers to a consolidation area
      See Also:

    • BUILTIN_DATABASE

      public static final String BUILTIN_DATABASE
      A built-in defined name that specified that the range specified is from a database data source
      See Also:

    • BUILTIN_SHEET_TITLE

      public static final String BUILTIN_SHEET_TITLE
      A built-in defined name that refers to a sheet title.
      See Also:

  • Method Details

    • getNameName

      public String getNameName()
      Returns the name that will appear in the user interface for the defined name.
      Specified by:
      getNameName in interface Name
      Returns:
      text name of this defined name

    • setNameName

      public void setNameName(String name)
      Sets the name that will appear in the user interface for the defined name. Names must begin with a letter or underscore, not contain spaces and be unique across the workbook.

      A name must always be unique within its scope. POI prevents you from defining a name that is not unique within its scope. However you can use the same name in different scopes. Example: 

      
 //by default names are workbook-global
 XSSFName name;
 name = workbook.createName();
 name.setNameName("sales_08");

 name = workbook.createName();
 name.setNameName("sales_08"); //will throw an exception: "The workbook already contains this name (case-insensitive)"

 //create sheet-level name
 name = workbook.createName();
 name.setSheetIndex(0); //the scope of the name is the first sheet
 name.setNameName("sales_08");  //ok

 name = workbook.createName();
 name.setSheetIndex(0);
 name.setNameName("sales_08");  //will throw an exception: "The sheet already contains this name (case-insensitive)"
      Specified by:
      setNameName in interface Name
      Parameters:
      name - name of this defined name
      Throws:
      IllegalArgumentException - if the name is invalid or the workbook already contains this name (case-insensitive)

    • getRefersToFormula

      public String getRefersToFormula()
      Description copied from interface: Name
      Returns the formula that the name is defined to refer to.
      Specified by:
      getRefersToFormula in interface Name
      Returns:
      the reference for this name, null if it has not been set yet. Never empty string
      See Also:

    • setRefersToFormula

      public void setRefersToFormula(String formulaText)
      Description copied from interface: Name
      Sets the formula that the name is defined to refer to. The following are representative examples:
      • 'My Sheet'!$A$3
      • 8.3
      • HR!$A$1:$Z$345
      • SUM(Sheet1!A1,Sheet2!B2)
      • -PMT(Interest_Rate/12,Number_of_Payments,Loan_Amount)
      Note: Using relative values like 'A1:B1' can lead to unexpected moving of the cell that the name points to when working with the workbook in Microsoft Excel, usually using absolute references like '$A$1:$B$1' avoids this, see also https://superuser.com/a/1031047/126954
      Specified by:
      setRefersToFormula in interface Name
      Parameters:
      formulaText - the reference for this name

    • isDeleted

      public boolean isDeleted()
      Description copied from interface: Name
      Checks if this name points to a cell that no longer exists
      Specified by:
      isDeleted in interface Name
      Returns:
      true if the name refers to a deleted cell, false otherwise

    • setSheetIndex

      public void setSheetIndex(int index)
      Tell Excel that this name applies to the worksheet with the specified index instead of the entire workbook.
      Specified by:
      setSheetIndex in interface Name
      Parameters:
      index - the sheet index this name applies to, -1 unsets this property making the name workbook-global

    • getSheetIndex

      public int getSheetIndex()
      Returns the sheet index this name applies to.
      Specified by:
      getSheetIndex in interface Name
      Returns:
      the sheet index this name applies to, -1 if this name applies to the entire workbook

    • setFunction

      public void setFunction(boolean value)
      Indicates that the defined name refers to a user-defined function. This attribute is used when there is an add-in or other code project associated with the file.
      Specified by:
      setFunction in interface Name
      Parameters:
      value - true indicates the name refers to a function.

    • getFunction

      public boolean getFunction()
      Indicates that the defined name refers to a user-defined function. This attribute is used when there is an add-in or other code project associated with the file.
      Returns:
      true indicates the name refers to a function.

    • setFunctionGroupId

      public void setFunctionGroupId(int functionGroupId)
      Specifies the function group index if the defined name refers to a function. The function group defines the general category for the function. This attribute is used when there is an add-in or other code project associated with the file.
      Parameters:
      functionGroupId - the function group index that defines the general category for the function

    • getFunctionGroupId

      public int getFunctionGroupId()
      Returns the function group index if the defined name refers to a function. The function group defines the general category for the function. This attribute is used when there is an add-in or other code project associated with the file.
      Returns:
      the function group index that defines the general category for the function

    • getSheetName

      public String getSheetName()
      Get the sheets name which this named range is referenced to
      Specified by:
      getSheetName in interface Name
      Returns:
      sheet name, which this named range referred to. Empty string if the referenced sheet name was not found.

    • isFunctionName

      public boolean isFunctionName()
      Is the name refers to a user-defined function ?
      Specified by:
      isFunctionName in interface Name
      Returns:
      true if this name refers to a user-defined function

    • isHidden

      public boolean isHidden()
      Checks if this name is hidden, eg one of the built-in Excel internal names
      Specified by:
      isHidden in interface Name
      Returns:
      true if this name is a hidden one

    • getComment

      public String getComment()
      Returns the comment the user provided when the name was created.
      Specified by:
      getComment in interface Name
      Returns:
      the user comment for this named range

    • setComment

      public void setComment(String comment)
      Specifies the comment the user provided when the name was created.
      Specified by:
      setComment in interface Name
      Parameters:
      comment - the user comment for this named range

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object o)
      Compares this name to the specified object. The result is true if the argument is XSSFName and the underlying CTDefinedName bean equals to the CTDefinedName representing this name
      Overrides:
      equals in class Object
      Parameters:
      o - the object to compare this XSSFName against.
      Returns:
      true if the XSSFName are equal; false otherwise.