In this topic
- About workspaces
- Connecting to a personal geodatabase workspace stored in Access
- Connecting to a file geodatabase workspace
- Connecting to an enterprise ArcSDE geodatabase workspace
- Connecting to a transactional version
- Connecting to a historical marker name
- Connecting to a historical time stamp
- Connecting to a personal or workgroup ArcSDE geodatabase workspace
- Connecting to a shapefile workspace using the geodatabase API
A workspace is a container of spatial and nonspatial datasets such as feature classes, raster datasets, and tables. Workspaces provide methods to instantiate existing datasets and create new datasets.
The following are the three types of workspaces (esriWorkspaceType):
- Shapefiles and ArcInfo workspaces are examples of an esriFileSystemWorkspace.
- A personal geodatabase stored in a Microsoft® Access or a file geodatabase are examples of an esriLocalDatabaseWorkspace.
- An ArcSDE geodatabase stored in a relational database management system (RDBMS) (such as Oracle®, DB2®, SQL Server™, or Informix®) is an example of an esriRemoteDatabaseWorkspace.
There are several methods that can be used to open a geodatabase workspace, each with its own purpose. This document reviews these methods for different types of workspaces and discusses when you may want to use one over the other.
To open a workspace, you need to create the appropriate workspace factory. Each workspace type has its own workspace factory.
A WorkspaceFactory is a dispenser of workspaces and allows a client to connect to a workspace specified by a set of connection properties. A WorkspaceFactory is a cocreatable, singleton object. A singleton object can only be instantiated once in a process. The WorkspaceFactory maintains a poll of currently connected, active workspaces that are referenced by the application. The workspace factory classes for geodatabase workspaces are found in the DataSourcesGDB library.
The following are the three different ways to open a workspace after creating the appropriate workspace factory:
- IWorkspaceFactory.Open—The Open method takes as input a set of connection properties that specify the workspace to establish a connection with.
- IWorkspaceFactory.OpenFromFile—The OpenFromFile method takes the path name of a file or directory that represents an esriFileSystemWorkspace, an esriLocalDatabaseWorkspace, or a connection file to an esriRemoteDatabaseWorkspace and returns the specified workspace.
- IWorkspaceFactory2.OpenFromString—The OpenFromString method on the IWorkspaceFactory2 interface was added to allow the opening of a workspace using a connection string that describes the connection properties for the workspace. The connection string is a collection of name value pairs separated by semicolons (;).
The workspace factory required to connect to a personal geodatabase is an AccessWorkspaceFactory. For local database workspaces, the IWorkspaceFactory.Open method usually requires a property set with a single property named DATABASE, whose values are the path name to the workspace.
The following code example accepts a string that is used to populate the required property to open and return a personal geodatabase workspace with the Open method:
[Java]
//For example, database = "C:\\myData\\mypGDB.mdb".
static IWorkspace open_pGDB_Workspace(String database)throws Exception{
IPropertySet propertySet = new PropertySet();
propertySet.setProperty("DATABASE", database);
IWorkspaceFactory workspaceFactory = new AccessWorkspaceFactory();
return workspaceFactory.open(propertySet, 0);
}
The OpenFromFile method for personal geodatabases requires the path name of the .mdb file that stores the Access database.
The following code example accepts the same string as the Open function, except it passes it directly into the OpenFromFile method instead of using it to create a property set. OpenFromFile is the most commonly used method to open personal geodatabases.
[Java]
//For example, pathToFile= "C:\\myData\\mypGDB.mdb".
static IWorkspace openFromFile_pGDB_Workspace(String pathToFile)throws Exception{
IWorkspaceFactory workspaceFactory = new AccessWorkspaceFactory();
return workspaceFactory.openFromFile(pathToFile, 0);
}
The last way to open a personal geodatabase is to utilize the OpenFromString method on IWorkspaceFactory2. The connection string used in this case is a collection of the name value pairs. For personal geodatabases, the collection only requires a name of DATABASE and a value of the path name to the workspace. See the following code example:
[Java]
//For example, connectionString = "DATABASE=C:\\myData\\mypGDB.mdb".
static IWorkspace openFromString_pGDB_Workspace(String connectionString)throws
Exception{
IWorkspaceFactory2 workspaceFactory = new AccessWorkspaceFactory();
return workspaceFactory.openFromString(connectionString, 0);
}
The required workspace factory to connect to a file geodatabase is FileGDBWorkspaceFactory.
The required code to connect to a file geodatabase is almost identical to the code for connecting to a personal geodatabase. Both are local database workspaces, but as stated previously, a different type of workspace factory is required. Additionally, the extension used on the database will be different. For a file geodatabase, the extension is .gdb.
The following code example uses the Open method to return a file geodatabase workspace:
The only differences between file and personal geodatabase connections are the workspace factory and the extension of the database.
//For example, database = "C:\\myData\\myfGDB.gdb".
static IWorkspace open_fGDB_Workspace(String database)throws Exception{
IPropertySet propertySet = new PropertySet();
propertySet.setProperty("DATABASE", database);
IWorkspaceFactory workspaceFactory = new FileGDBWorkspaceFactory();
return workspaceFactory.open(propertySet, 0);
}
The OpenFromFile method can also be used to open a file geodatabase workspace. As with the personal geodatabase workspace, OpenFromFile is the most commonly used method to open a file geodatabase workspace. See the following code example:
[Java]
//For example, pathToFile= "C:\\myData\\myfGDB.gdb".
static IWorkspace openFromFile_fGDB_Workspace(String pathToFile)throws Exception{
IWorkspaceFactory workspaceFactory = new FileGDBWorkspaceFactory();
return workspaceFactory.openFromFile(pathToFile, 0);
}
File geodatabases can also be opened using the IWorkspaceFactory.OpenFromString method as shown in the following code example. This method is often more convenient than building the property set used with Open.
[Java]
//For example, connectionString = "DATABASE=C:\\myData\\myfGDB.gdb".
static IWorkspace openFromString_fGDB_Workspace(String connectionString)throws
Exception{
IWorkspaceFactory2 workspaceFactory = new FileGDBWorkspaceFactory();
return workspaceFactory.openFromString(connectionString, 0);
}
SdeWorkspaceFactory is the required workspace factory to connect to an ArcSDE geodatabase. The connection properties of an esriRemoteDatabaseWorkspace specify the server and instance to connect to and can be saved in a connection file (.sde) on the file system.
In the case of remote database workspaces accessed via ArcSDE, the properties can include the following connection properties of the database being connected to:
- SERVER—The SDE server name you are connecting to.
- INSTANCE—The instance you are connecting to.
- DATABASE—The database connected to. The DATABASE property is optional and is required for ArcSDE instances that manage multiple databases (for example, SQL Server).
- USER—The connected user.
- PASSWORD—The connected user's password.
- AUTHENTICATION_MODE—The credential authentication mode of the connection. Acceptable values are the operating system authentication (OSA) and database management system (DBMS); the default is DBMS. If the AUTHENTICATION_MODE is OSA, the USER and PASSWORD properties are not required. OSA uses the operating system credentials to establish a connection with the database.
- VERSION—The transactional version to connect to. The acceptable value is a string that represents a transaction version name.
- HISTORICAL_NAME—The historical version to connect to. The acceptable value is a string that represents a historical marker name.
- HISTORICAL_TIMESTAMP—The moment in history to establish a historical version connection. The acceptable value is a date object containing a date time that represents a moment time stamp. The formatting of the date is DBMS specific (for example, SQLServer = "1/1/2006 12:00:01 AM").
Since the workspace connection can only represent one version, only one of the three version properties (VERSION, HISTORICAL_NAME, or HISTORICAL_TIMESTAMP) should be used.
If no version is supplied, then a connection to the default transactional version will be returned.
If any of the Open methods for a workspace are called with insufficient properties, a connection dialog box appears and prompts you for the required properties. This can be used with ArcSDE workspaces to allow the user to connect with specific credentials (for example, enter a specific user name or password).
In the following code example, a property set is populated from supplied strings to make a connection to an ArcSDE geodatabase workspace with a transactional version. The property set is then used by the Open method to return a workspace. This approach involves the most code; however, it can be customized into a general function for connecting to ArcSDE databases based on supplied parameters from the user.
[Java]
//For example, server = "Kona".
//Database = "SDE" or "" if Oracle.
//Instance = "5151".
//User = "vtest".
//Password = "go".
//Version = "SDE.DEFAULT".
static IWorkspace open_ArcSDE_Workspace(String server, String instance, String user,
String password, String database, String version)throws Exception{
IPropertySet propertySet = new PropertySet();
propertySet.setProperty("SERVER", server);
propertySet.setProperty("INSTANCE", instance);
propertySet.setProperty("DATABASE", database);
propertySet.setProperty("USER", user);
propertySet.setProperty("PASSWORD", password);
propertySet.setProperty("VERSION", version);
IWorkspaceFactory workspaceFactory = new SdeWorkspaceFactory();
return workspaceFactory.open(propertySet, 0);
}
If you have archiving enabled on data in your ArcSDE database, you are able to connect to a historical version. It is possible to create a named marker at some point. These markers are created with IHistoricalWorkspace and can be used to make a connection to this specific time.
To connect to a historical marker, augment the property set and replace the VERSION property with a HISTORICAL_NAME property. In the following code example, the name of the historical marker is Year End 2006:
[Java]
//For example, server = "Kona".
//Database = "SDE" or "" if Oracle.
//Instance = "5151".
//User = "vtest".
//Password = "go".
//Historical_name = "Year End 2006".
static IWorkspace open_ArcSDE_Workspace(String server, String instance, String user,
String password, String database, String historical_name)throws Exception{
IPropertySet propertySet = new PropertySet();
propertySet.setProperty("SERVER", server);
propertySet.setProperty("INSTANCE", instance);
propertySet.setProperty("DATABASE", database);
propertySet.setProperty("USER", user);
propertySet.setProperty("PASSWORD", password);
propertySet.setProperty("HISTORICAL_NAME", historical_name);
IWorkspaceFactory workspaceFactory = new SdeWorkspaceFactory();
return workspaceFactory.open(propertySet, 0);
}
It is also possible to connect at any time with the historical time stamp property. The following code replaces the Historical_Name property with the Historical_Timestamp to connect to an ArcSDE workspace on SQL Server. It is good practice to convert a string representing a date to a date object when using it throughout the archiving application programming interface (API). This allows any date conversion errors to be handled before they are used to connect to a workspace.
[Java]
//For example, server = "Kona".
// Database = "sde".
// Instance = "5151".
// User = "vtest".
// Password = "go".
// TimeStamp = "1/1/2006 12:00:01 AM".
static IWorkspace open_ArcSDE_Workspace(String server, String instance, String user,
String password, String database, String timestamp)throws Exception{
IPropertySet propertySet = new PropertySet();
propertySet.setProperty("SERVER", server);
propertySet.setProperty("INSTANCE", instance);
propertySet.setProperty("DATABASE", database);
propertySet.setProperty("USER", user);
propertySet.setProperty("PASSWORD", password);
propertySet.setProperty("HISTORICAL_TIMESTAMP", timestamp);
IWorkspaceFactory workspaceFactory = new SdeWorkspaceFactory();
return workspaceFactory.open(propertySet, 0);
}
If you or your company have chosen to use ArcSDE connection files created in ArcCatalog (or programmatically with IWorkspaceFactory.Create) and stored on disk to organize and distribute the connection information for your ArcSDE geodatabases, the OpenFromFile method may be the way that connections to ArcSDE geodatabase workspaces are made.
In the following code example, the path to the .sde connection file stored on disk is used to create the connection with the OpenFromFile method:
[Java]
//For example, pathToFile= "C:\\myData\\Connection to Kona.sde".
static IWorkspace openFromFile_ArcSDE_Workspace(String pathToFile)throws Exception{
IWorkspaceFactory workspaceFactory = new SdeWorkspaceFactory();
//The hWnd argument is the parent window or the application's window.
//The hWnd will guarantee that the connection dialog box if shown to you because of
//insufficient properties, has the correct parent.
return workspaceFactory.openFromFile(pathToFile, 0);
}
The OpenFromString method is most commonly used for convenience. For example, you have a specific application that accesses an ArcSDE geodatabase to which the connection properties are well known. In this case, creating a string of the name value pairs may be easier then creating a property set for the same parameters.
In the following code example, connection is made to the same ArcSDE instance as in the Open method example, except as a different user:
[Java]
//For example, connectionString = "SERVER=Kona;DATABASE=sde;INSTANCE=5151;USER=Editor;PASSWORD=Editor;VERSION=sde.DEFAULT".
static IWorkspace openFromString_ArcSDE_Workspace(String connectionString)throws
Exception{
IWorkspaceFactory2 workspaceFactory = (IWorkspaceFactory2)new
SdeWorkspaceFactory();
return workspaceFactory.openFromString(connectionString, 0);
}
Personal and workgroup ArcSDE geodatabases are a workspace type of esriRemoteDatabaseWorkspace (for example, enterprise ArcSDE geodatabases) and also use the SdeWorkspaceFactory to make a connection to the workspace.
The required code to make a connection to a personal or workgroup ArcSDE geodatabase is exactly the same. The code for both is also very similar to that of an enterprise ArcSDE geodatabase. Personal and workgroup ArcSDE geodatabases only support connections using direct connect and do not support the three-tier connections that an enterprise ArcSDE does.
Additionally, connections can only be made using the OSA where the user's operating system credentials are used for the user name and password. The geodatabases in a personal and workgroup ArcSDE are always owned by the dbo user (the version name is prefixed by dbo).
You can see the slight differences in the following example code. The direct connection is set up in the instance property. In this code example, the AUTHENTICATION_MODE property is also introduced. This property defaults to DBMS, which means that the DBMS will be used to authenticate the user's credentials. You can see that the authentication mode has been set to OSA in lieu of passing in the user name and password.
[Java]
// For example, for direct connect with OSA authentication.
// Server = "tivo_sqlexpress".
// Database = "sewer".
// Instance = "sde:sqlserver:tivo\\sqlexpress"
// Authenticaion_mode = "OSA".
// Version = "dbo.DEFAULT".
static IWorkspace open_Workgroup_ArcSDE_Workspace(String server, String instance,
String authentication_mode, String database, String version)throws Exception{
IPropertySet propertySet = new PropertySet();
propertySet.setProperty("SERVER", server);
propertySet.setProperty("INSTANCE", instance);
propertySet.setProperty("DATABASE", database);
propertySet.setProperty("AUTHENTICATION_MODE", authentication_mode);
propertySet.setProperty("VERSION", version);
IWorkspaceFactory workspaceFactory = new SdeWorkspaceFactory();
return workspaceFactory.open(propertySet, 0);
}
The OpenFromFile method can also be used to connect to a personal or workgroup ArcSDE geodatabase. These files can be created manually in ArcCatalog, or if you connect from the database server, you can right-click the geodatabase and choose Save Connection. This will create a .sde connection file in your Database Connections folder.
The connection files are then used in the OpenFromFile method as shown in the following code example:
[Java]
//For example, pathToFile= "C:\\myData\\Connection to tivo.sde".
static IWorkspace openFromFile_Workgroup_ArcSDE_Workspace(String pathToFile)throws
Exception{
IWorkspaceFactory workspaceFactory = new SdeWorkspaceFactory();
//The hWnd argument is the parent window or application's window.
//The hWnd will guarantee that the connection dialog box, if presented to you because of
//insufficient properties, has the correct parent.
return workspaceFactory.openFromFile(pathToFile, 0);
}
The OpenFromString method code example is only different from an enterprise ArcSDE because of the content of the string that is passed in. Ensure that OSA is set and that direct connect is used for the instance property value pair. See the following code example:
[Java]
//For example, connectionString = "SERVER=tivo_sqlexpress;DATABABSE=sewer;INSTANCE=sde:sqlserver:tivo\sqlexpress;AUTEHENTICATION_MODE=OSA;VERSION=dbo.DEFAULT".
static IWorkspace openFromString_Workgroup_ArcSDE_Workspace(String connectionString)
throws Exception{
IWorkspaceFactory2 workspaceFactory = new SdeWorkspaceFactory();
return workspaceFactory.openFromString(connectionString, 0);
}
The DataServerManager object is used to access and administer one or more geodatabases stored on a data server. You can open a connection to each geodatabase in a DataServer through the use of the IWorkspaceName and IName interfaces. Unlike an enterprise ArcSDE geodatabase, opening a connection to a geodatabase stored in a personal or workgroup ArcSDE does not require a set of properties. Instead, the geodatabase name, type of version, and version specifier are used.
There are only three types of versions that can be used to connect to the geodatabase:
- VERSION—Transactional version to connect to. The acceptable value is a string that represents a transaction version name.
- HISTORICAL_NAME—Historical version to connect to. The acceptable value is a string that represents a historical marker name.
- HISTORICAL_TIMESTAMP—Moment in history to establish a historical version connection. The acceptable value is a date object containing a date time that represents a moment time stamp.
The version specifier must correspond to the type of version (for example, if VERSION is specified, the version name must be listed as the version specifier). Also, since
the workspace connection can only represent one version, only one of the three version properties (VERSION, or HISTORICAL_NAME, or HISTORICAL_TIMESTAMP) should be used.
The following code example shows how to connect to a transactional version of a geodatabase stored in a DataServer for a personal or workgroup ArcSDE using the DataServerManager:
[Java]
// For example, serverName = "tivo\\sqlexpress"
// gdbName = "sewer"
// versionPropName = "VERSION"
// versionName = "dbo.DEFAULT"
public static IWorkspace workgroupArcSdeWorkspaceFromDSM(String serverName, String
gdbName, String versionPropName, String versionName)throws Exception{
// Create a Data Server Manager object.
IDataServerManager dataserverManager = new DataServerManager();
//Set the server name and connect to the server.
dataserverManager.setServerName("tivo\\sqlexpress");
dataserverManager.connect();
//Open one of the geodatabases in the Database Server.
IDataServerManagerAdmin dataservermanagerAdmin = (IDataServerManagerAdmin)
dataserverManager;
IWorkspaceName workspaceName = dataservermanagerAdmin.createWorkspaceName
(gdbName, versionPropName, versionName);
//Cast from the workspace name to utilize the Open method.
IName name = (IName)workspaceName;
IWorkspace workspace = new IWorkspaceProxy(name.open());
return workspace;
}
The geodatabase is not only a physical store for geographic data, it is also the API used to access other types of geographic data with ArcGIS. Therefore, the geodatabase API can be used to access non-geodatabase workspaces such as shapefiles. Shapefiles have a workspace type of esriFileSystemWorkspace.
Like the geodatabase workspace, a workspace factory must be created to access a shapefile workspace. Unlike the geodatabase, the workspacefactory for shapefiles is found in the DataSourcesFile library.
In the following code example, the Open method is used with a shapefile workspace factory to return the shapefile workspace. The workspace for shapefiles is the folder they are stored in.
[Java]
//For example, database = "C:\\myData".
static IWorkspace open_shapefile_Workspace(String database)throws Exception{
IPropertySet propertySet = new PropertySet();
propertySet.setProperty("DATABASE", database);
IWorkspaceFactory workspaceFactory = new ShapefileWorkspaceFactory();
return workspaceFactory.open(propertySet, 0);
}
The OpenFromFile method can also be used to open a shapefile geodatabase workspace. This method requires only the path of the folder containing your shapefile and is therefore often the simplest solution for connecting to a shapefile workspace.
[Java]
//For example, path= "C:\\myData\\".
static IWorkspace openFromFile_shapefile_Workspace(String path)throws Exception{
IWorkspaceFactory workspaceFactory = new ShapefileWorkspaceFactory();
return workspaceFactory.openFromFile(path, 0);
}
As with geodatabase workspaces, shapefile workspaces also support the IWorkspaceFactory2 interface and have an OpenFromString method. As you can see in the following code example, the input string is slightly larger than required for the OpenFromFile method and might reduce the convenience normally associated with this method.
[Java]
//For example, connectionString = "DATABASE=C:\\myData".
static IWorkspace openFromString_shapefile_Workspace(String connectionString)throws
Exception{
IWorkspaceFactory2 workspaceFactory = (IWorkspaceFactory2)new
ShapefileWorkspaceFactory();
return workspaceFactory.openFromString(connectionString, 0);
}
Along with shapefiles, coverages also have a workspace type of esriFileSystemWorkspace, and can be accessed (with limited functionality) through the geodatabase API. The workspace for coverages is not a folder containing .pat and .adf files, but rather the parent directory with access to both that directory as well as the coverage's info directory. Although all three methods for opening shapefile workspaces will work with coverages, only one code example is shown below, as the process of opening coverage workspaces is the same as opening shapefile workspaces, with the exception of the type of factory used.
In the following code example, the Open method is used with a shapefile workspace factory to return the shapefile workspace.
[Java]
// For example, path = "C:\\myData".
public static IWorkspace coverageWorkspaceFromPropertySet(String path)throws
Exception{
IPropertySet propertySet = new PropertySet();
propertySet.setProperty("DATABASE", path);
IWorkspaceFactory workspaceFactory = new ArcInfoWorkspaceFactory();
return workspaceFactory.open(propertySet, 0);
}
See Also:
Sample: Connect to a shapefile workspaceSample: Connect to a Personal Geodatabase
| Development licensing | Deployment licensing |
|---|---|
| ArcGIS for Desktop Basic | ArcGIS for Desktop Basic |
| ArcGIS for Desktop Standard | ArcGIS for Desktop Standard |
| ArcGIS for Desktop Advanced | ArcGIS for Desktop Advanced |
| Engine Developer Kit | Engine |