Class WorkbookReference

java.lang.Object

com.grapecity.documents.excel.expressions.WorkbookReference

public final class WorkbookReference extends Object

Represents a reference to an external workbook.

This class identifies an external workbook by file path, URI, or workbook name and is typically used together with Reference when building or modifying formula references. A workbook reference can be created by using FromFilePath(String), FromUri(String), or FromName(String).


 com.grapecity.documents.excel.expressions.NameNode nameNode = new com.grapecity.documents.excel.expressions.NameNode("January");
 nameNode.setWorksheetName("Sheet1");
 nameNode.setWorkbook(WorkbookReference.FromName("Sales.xlsx"));

Field Summary

Fields

Modifier and Type

Field

Description

static final boolean

SupportsReferenceId
Constructor Summary

Constructors

Constructor

Description

WorkbookReference()
Method Summary

Modifier and Type

Method

Description

boolean

equals(WorkbookReference other)

Checks whether this workbook reference is equal to another workbook reference.

boolean

equals(Object obj)

Checks whether this workbook reference is equal to the specified object.

static WorkbookReference

FromFilePath(String workbookFullPath)

Creates a workbook reference from a file path.

static WorkbookReference

FromName(String name)

Creates a workbook reference from a workbook name.

static WorkbookReference

FromUri(String uri)

Creates a workbook reference from an absolute URI to a workbook.

String

getBaseDirectory()

Gets the base directory that contains the workbook.

String

getBaseUri()

Gets the base URI that contains the workbook.

int

getId()

Gets the workbook id if the reference came from low-level storage of formulas.

String

getName()

Gets the name of the workbook.

int

hashCode()

Gets the hash code for this workbook reference.

String

toString()

Gets the string representation of this workbook reference.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details
- SupportsReferenceId
  
  public static final boolean SupportsReferenceId
Constructor Details
- WorkbookReference
  
  public WorkbookReference()
Method Details
- getBaseDirectory
  
  public String getBaseDirectory()
  Gets the base directory that contains the workbook.
  If the returned value is not null, getName() represents the file name of the workbook. If the returned value is an empty string, the path is the root directory.
  
  String workbookFullPath = java.nio.file.Paths.get("Users", "DefaultApps", "Documents", "Budget.xlsx").toString(); WorkbookReference reference = WorkbookReference.FromFilePath(workbookFullPath); String baseDirectory = reference.getBaseDirectory();
  Returns:
  
  The base directory that contains the workbook. Returns an empty string if the workbook path is in the root directory, or null if no base directory is available.
- getBaseUri
  
  public String getBaseUri()
  Gets the base URI that contains the workbook.
  If the returned value is not null, getName() returns the workbook file name.
  
  For example, for the URI https://www.example.com/file/example.xlsx, the base URI is https://www.example.com/file and the workbook name is example.xlsx.
  
  WorkbookReference reference = WorkbookReference.FromUri("https://somesite.com/files/sample.xlsx"); String baseUri = reference.getBaseUri();
  Returns:
  
  The base URI that contains the workbook, or null if this workbook reference does not use a URI-based location.
- getName
  
  public String getName()
  Gets the name of the workbook.
  If getBaseDirectory() is not null, the returned value represents the file name of the workbook. If this reference was created by FromName(String), the returned value is the workbook name that was provided when the reference was created.
  
  String workbookFullPath = java.nio.file.Paths.get("Users", "DefaultApps", "Documents", "Budget.xlsx").toString(); WorkbookReference reference = WorkbookReference.FromFilePath(workbookFullPath); String name = reference.getName();
  Returns:
  
  The workbook name. If this reference has a base directory, the returned value is the workbook file name.
- getId
  
  public int getId()
  Gets the workbook id if the reference came from low-level storage of formulas.
  The default value is 0, which indicates the current workbook.
  
  String workbookFullPath = java.nio.file.Paths.get("Users", "DefaultApps", "Documents", "Budget.xlsx").toString(); WorkbookReference reference = WorkbookReference.FromFilePath(workbookFullPath); int id = reference.getId();
  Returns:
  
  The workbook id. Returns 0 for the current workbook.
- FromFilePath
  
  public static WorkbookReference FromFilePath(String workbookFullPath)
  Creates a workbook reference from a file path.
  This method splits the specified path into a base directory and workbook name. If the path points to a workbook in the root directory, the returned reference uses an empty string for getBaseDirectory().
  
  String workbookFullPath = java.nio.file.Paths.get("Users", "DefaultApps", "Documents", "Budget.xlsx").toString(); WorkbookReference reference = WorkbookReference.FromFilePath(workbookFullPath); String baseDirectory = reference.getBaseDirectory(); String name = reference.getName();
  Parameters:
  
  workbookFullPath - The full path of the workbook. Must not be null or empty, and must contain both a directory part and a file name.
  
  Returns:
  
  A WorkbookReference created from the specified file path.
  
  Throws:
  
  NullPointerException - if workbookFullPath is null or empty.
  
  IllegalArgumentException - if the specified path does not contain a directory part or does not contain a file name.
- FromUri
  
  public static WorkbookReference FromUri(String uri)
  Creates a workbook reference from an absolute URI to a workbook.
  This method creates a reference whose base URI is the URI path up to, but not including, the workbook file name. File URIs are not supported. The specified URI must be absolute, must contain a host, and must contain a workbook file name.
  
  WorkbookReference reference = WorkbookReference.FromUri("https://somesite.com/files/sample.xlsx"); String baseUri = reference.getBaseUri(); String name = reference.getName();
  Parameters:
  
  uri - The absolute URI of the workbook. Must not be null, must not be a file URI, and must include both a host and a file name.
  
  Returns:
  
  A WorkbookReference created from the specified URI.
  
  Throws:
  
  IllegalArgumentException - if uri is not a valid absolute URI, if it is a file URI, or if it does not contain a host or workbook file name.
- FromName
  
  public static WorkbookReference FromName(String name)
  Creates a workbook reference from a workbook name.
  Use this method when the workbook should be identified by name rather than by a file path or URI. The specified name can be different from the file name.
  
  WorkbookReference reference = WorkbookReference.FromName("Budget"); String name = reference.getName();
  Parameters:
  
  name - The workbook name. Must not be null or empty.
  
  Returns:
  
  A WorkbookReference that stores the specified workbook name.
  
  Throws:
  
  NullPointerException - if name is null or empty.
- equals
  
  public boolean equals(Object obj)
  
  Checks whether this workbook reference is equal to the specified object.
  This method returns true only when obj is a WorkbookReference and its base directory, workbook name, base URI, and workbook ID are equal to those of the current instance. If obj is not a WorkbookReference, this method forwards null to equals(WorkbookReference) and returns false.
  
  Overrides:
  
  equals in class Object
  
  Parameters:
  
  obj - The object to compare with this workbook reference. If obj is not a WorkbookReference, this method returns false.
  
  Returns:
  
  true if obj is a WorkbookReference with the same base directory, workbook name, base URI, and workbook ID; otherwise, false.
- equals
  
  public boolean equals(WorkbookReference other)
  
  Checks whether this workbook reference is equal to another workbook reference.
  This method returns true only when other is not null and its base directory, workbook name, base URI, and workbook ID are equal to those of the current instance.
  
  Parameters:
  
  other - The workbook reference to compare with this workbook reference. If other is null, this method returns false.
  
  Returns:
  
  true if other has the same base directory, workbook name, base URI, and workbook ID as this workbook reference; otherwise, false.
- hashCode
  
  public int hashCode()
  
  Gets the hash code for this workbook reference.
  The returned hash code is computed from the base directory, base URI, workbook name, and workbook ID of this instance. References that are equal according to equals(Object) return the same hash code.
  
  Overrides:
  
  hashCode in class Object
  
  Returns:
  
  The hash code for this workbook reference.
- toString
  
  public String toString()
  
  Gets the string representation of this workbook reference.
  The returned string depends on how the reference was created. If this reference has no workbook name, the returned string is the workbook ID enclosed in square brackets. If it uses a base URI, the returned string combines the unescaped base URI with the unescaped workbook name in square brackets. If it stores only a workbook name, the returned string is the name enclosed in square brackets. If it uses a base directory, the returned string combines the base directory and the workbook name in square brackets.
  
  Overrides:
  
  toString in class Object
  
  Returns:
  
  The string representation of this workbook reference.

Class WorkbookReference

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

SupportsReferenceId

Constructor Details

WorkbookReference

Method Details

getBaseDirectory

getBaseUri

getName

getId

FromFilePath

FromUri

FromName

equals

equals

hashCode

toString