com.esri.arcgis.geodatabase
Interface IWorkspaceFactory

All Superinterfaces:
Serializable
All Known Subinterfaces:
IWorkspaceFactory2
All Known Implementing Classes:
AccessWorkspaceFactory, AMSWorkspaceFactory, ArcInfoWorkspaceFactory, CadWorkspaceFactory, ExcelWorkspaceFactory, FileGDBWorkspaceFactory, IMSWorkspaceFactory, InMemoryWorkspaceFactory, IWorkspaceFactory2Proxy, IWorkspaceFactoryProxy, NetCDFWorkspaceFactory, OLEDBWorkspaceFactory, PCCoverageWorkspaceFactory, PlugInWorkspaceFactory, RasterWorkspaceFactory, SDCWorkspaceFactory, SdeWorkspaceFactory, ShapefileWorkspaceFactory, StreetMapWorkspaceFactory, TextFileWorkspaceFactory, TinWorkspaceFactory, ToolboxWorkspaceFactory, VpfWorkspaceFactory, WorkspaceFactory

public interface IWorkspaceFactory
extends Serializable

Provides access to members that create and open workspaces and supply workspace factory information.

Superseded By

IWorkspaceFactory2

Remarks

A WorkspaceFactory is a dispenser of workspaces and allows a client to connect to a workspace specified by a set of connection properties. A workspace represents a database or a datasource that contains one or more datasets. Examples of datasets include tables, feature classes and relationship classes. A WorkspaceFactory is a cocreatable, singleton object. Connection properties are specified using a PropertySet object and can be saved to a connection file. A WorkspaceFactory also supports methods that can be used to browse and manage file system workspaces, and methods to manage connection files for remote database workspaces.

Each workspace factory maintains a pool of currently connected, active workspaces that are referenced by the application. When any of the Open* methods is called, the workspace factory first checks to see if a workspace has previously been opened with a matching set of properties. If so, a reference to the existing instance is returned. In the case of ArcSDE workspaces, when an application connects to a workspace but omits some connection properties (such as username, password, or version), the workspace factory will check a set of "core" properties - SERVER, INSTANCE, and AUTHENTICATION_MODE - to see they match any open workspaces. If so, the workspace factory will return a reference to the matching workspace.

When To Use

Use IWorkspaceFactory when you need to create a new workspace, connect to an existing workspace or find information about a workspace.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

IWorkspaceFactory rasWkspFactory = new RasterWorkspaceFactory();

IWorkspace wksp = new RasterWorkspace(rasWkspFactory.openFromFile(aPath, 0));


Method Summary
 boolean containsWorkspace(String parentDirectory, IFileNames fileNames)
          Indicates if parentDirectory contains a valid workspace, or is a valid file-system workspace.
 boolean copy(IWorkspaceName workspaceName, String destinationFolder, IWorkspaceName[] workspaceNameCopy)
          Copies a workspace to the specified destination folder.
 IWorkspaceName create(String parentDirectory, String name, IPropertySet connectionProperties, int hWnd)
          Creates a new workspace specified by the directory, file name, and connection properties.
 IUID getClassID()
          The class ID of the WorkspaceFactory.
 String getWorkspaceDescription(boolean plural)
          A singular or plural description of the type of workspace the workspace factory opens/creates.
 IWorkspaceName getWorkspaceName(String parentDirectory, IFileNames fileNames)
          Retrieves the workspace name of a workspace from the given list of file names.
 int getWorkspaceType()
          The type of workspace the workspace factory opens/creates.
 boolean isWorkspace(String fileName)
          True if the specified file identifies a workspace supported by the workspace factory.
 boolean move(IWorkspaceName workspaceName, String destinationFolder)
          Moves a workspace to the specified destination folder.
 IWorkspace open(IPropertySet connectionProperties, int hWnd)
          Opens the workspace specified by the connection properties.
 IWorkspace openFromFile(String fileName, int hWnd)
          Opens the workspace specified by the given file name.
 IPropertySet readConnectionPropertiesFromFile(String fileName)
          The connection properties from the specified file.
 

Method Detail

open

IWorkspace open(IPropertySet connectionProperties,
                int hWnd)
                throws IOException,
                       AutomationException
Opens the workspace specified by the connection properties.

Remarks

Open takes as input a property set of connection properties that specify the workspace to connect to. In the case of file system workspaces and local database workspaces, a single property named DATABASE, whose value is the pathname to the workspace, is usually all that is required. In the case of remote database workspaces accessed via ArcSDE the properties can include the USER, PASSWORD, DATABASE, SERVER, INSTANCE, VERSION, HISTORICAL_NAME, HISTORICAL_TIMESTAMP, and AUTHENTICATION_MODE properties of the database being connected to.

List of acceptable connection property names and a brief description of each

"SERVER" – SDE server name you are connecting to.

"INSTANCE" – Instance you are connection to.

"DATABASE" – Database connected to.

"USER" – Connected user.

"PASSWORD" – Connected password.

"AUTHENTICATION_MODE" – Credential authentication mode of the connection. Acceptable values are "OSA" and "DBMS".

"VERSION" – Transactional version to connect to. Acceptable value is a string that represents a transaction version name.

"HISTORICAL_NAME" – Historical version to connect to. Acceptable value is a string type that represents a historical marker name.

"HISTORICAL_TIMESTAMP" – Moment in history to establish an historical version connection. Acceptable value is a date time that represents a moment timestamp.

Notes:

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
connectionProperties - A reference to a com.esri.arcgis.system.IPropertySet (in)
hWnd - The hWnd (A COM typedef) (in)
Returns:
A reference to a com.esri.arcgis.geodatabase.IWorkspace
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

openFromFile

IWorkspace openFromFile(String fileName,
                        int hWnd)
                        throws IOException,
                               AutomationException
Opens the workspace specified by the given file name.

Remarks

OpenFromFile takes the pathname of a file or directory that represents either a FileSystemWorkspace or LocalDatabaseWorkspace, or a connection file to a RemoteDatabase workspace and returns an interface on the specified workspace. Clients of these methods can then proceed to open and access datasets in the workspace. If these methods are called with insufficient properties, then the user will be presented with a connection dialog that will prompt for the required properties.

The hWnd argument is the parent window or application's window. The hWnd will guarantee that the connection dialog, if presented to you because of insufficient properties, has the correct parent.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
fileName - The fileName (in)
hWnd - The hWnd (A COM typedef) (in)
Returns:
A reference to a com.esri.arcgis.geodatabase.IWorkspace
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

create

IWorkspaceName create(String parentDirectory,
                      String name,
                      IPropertySet connectionProperties,
                      int hWnd)
                      throws IOException,
                             AutomationException
Creates a new workspace specified by the directory, file name, and connection properties.

Remarks

Create has different results depending on the type of workspace factory. If you are working with ArcSDE, a new connection file (.sde) is created. If you are working with an ArcInfo workspace factory, then a folder with an INFO subfolder is created. The optional ConnectionProperties parameter specifies any additional connection properties needed, such as the server, instance, user and password in the case where a connection file to a remote database workspace is being created. If no connection properties are specified, then this method will result in a dialog being displayed that prompts the user for the required properties.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
parentDirectory - The parentDirectory (in)
name - The name (in)
connectionProperties - A reference to a com.esri.arcgis.system.IPropertySet (in)
hWnd - The hWnd (A COM typedef) (in)
Returns:
A reference to a com.esri.arcgis.geodatabase.IWorkspaceName
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

containsWorkspace

boolean containsWorkspace(String parentDirectory,
                          IFileNames fileNames)
                          throws IOException,
                                 AutomationException
Indicates if parentDirectory contains a valid workspace, or is a valid file-system workspace.

Remarks

ContainsWorkspace is useful when browsing the file system for workspaces. It takes a parent directory and the list of file names in the directory to be examined. It returns true if the parent directory represents a workspace covered by this factory or if the parent directory contains a workspace or a connection file to a workspace covered by this factory.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
parentDirectory - The parentDirectory (in)
fileNames - A reference to a com.esri.arcgis.system.IFileNames (in)
Returns:
The containsWorkspace
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getWorkspaceName

IWorkspaceName getWorkspaceName(String parentDirectory,
                                IFileNames fileNames)
                                throws IOException,
                                       AutomationException
Retrieves the workspace name of a workspace from the given list of file names.

Remarks

GetWorkspaceName is useful when browsing the file system for workspaces. It is handed in a parent directory and the list of file names in the directory to be examined. It returns a WorkspaceName object representing the first workspace it finds in the list of filenames and removes any filenames representing the workspace from the input list of filenames.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
parentDirectory - The parentDirectory (in)
fileNames - A reference to a com.esri.arcgis.system.IFileNames (in)
Returns:
A reference to a com.esri.arcgis.geodatabase.IWorkspaceName
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getClassID

IUID getClassID()
                throws IOException,
                       AutomationException
The class ID of the WorkspaceFactory.

Remarks

GetClassID returns the unique identifier for the workspace factory. You can use this to distinguish different versions of the same type of factory, for example, whether you are working with an SDEWorkspace, FileGDBWorkspace or AccessWorkspace factory.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.system.IUID
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isWorkspace

boolean isWorkspace(String fileName)
                    throws IOException,
                           AutomationException
True if the specified file identifies a workspace supported by the workspace factory.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
fileName - The fileName (in)
Returns:
The isWorkspace
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

readConnectionPropertiesFromFile

IPropertySet readConnectionPropertiesFromFile(String fileName)
                                              throws IOException,
                                                     AutomationException
The connection properties from the specified file.

Remarks

The filename parameter represents the pathname of a file that contains the connection information to be placed into the IPropertySet variable. When used with ArcSDE connection files, the pathname generally points to a binary file in the directory %USERPROFILE%\Application Data\ESRI\ArcCatalog.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
fileName - The fileName (in)
Returns:
A reference to a com.esri.arcgis.system.IPropertySet
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getWorkspaceDescription

String getWorkspaceDescription(boolean plural)
                               throws IOException,
                                      AutomationException
A singular or plural description of the type of workspace the workspace factory opens/creates.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:
plural - The plural (in)
Returns:
The description
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getWorkspaceType

int getWorkspaceType()
                     throws IOException,
                            AutomationException
The type of workspace the workspace factory opens/creates.

Remarks

The WorkspaceType property of a WorkspaceFactory returns information on the type of workspace managed by the WorkspaceFactory. Workspaces are classified into the following types specified by the esriWorkspaceType enumeration; FileSystemWorkspace, LocalDatabaseWorkspace, and RemoteDatabaseWorkspace.
See esriWorkspaceType for information on the types of workspaces.
Shapefiles and ArcInfo workspaces are examples of FileSystemWorkspace. A Personal Geodatabase stored in Access or a File Geodatabase is an example of a LocalDatabaseWorkspace . An ArcSDE Geodatabase stored in an RDBMS such as Oracle, DB2, SqlServer, or Informix and accessed via ArcSDE is an example of a RemoteDatabaseWorkspace.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Returns:
A com.esri.arcgis.geodatabase.esriWorkspaceType constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

copy

boolean copy(IWorkspaceName workspaceName,
             String destinationFolder,
             IWorkspaceName[] workspaceNameCopy)
             throws IOException,
                    AutomationException
Copies a workspace to the specified destination folder.

Remarks

The Copy and Move methods can be used to copy or move workspaces or connection files between folders in the file system. The Boolean result indicates if the operation was successful. In the case of remote database workspaces, these operations work on the connection file representing the workspace.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
workspaceName - A reference to a com.esri.arcgis.geodatabase.IWorkspaceName (in)
destinationFolder - The destinationFolder (in)
workspaceNameCopy - A reference to a com.esri.arcgis.geodatabase.IWorkspaceName (out: use single element array)
Returns:
The successfulCopy
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

move

boolean move(IWorkspaceName workspaceName,
             String destinationFolder)
             throws IOException,
                    AutomationException
Moves a workspace to the specified destination folder.

Remarks

The Copy and Move methods can be used to copy or move workspaces or connection files between folders in the file system. The Boolean result indicates if the operation was successful. In the case of remote database workspaces, these operations work on the connection file representing the workspace.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
workspaceName - A reference to a com.esri.arcgis.geodatabase.IWorkspaceName (in)
destinationFolder - The destinationFolder (in)
Returns:
The successfulMove
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.