1. Guide
  2. Administering Oracle Spatial Studio

2 Administering Oracle Spatial Studio

Administering Oracle Spatial Studio involves certain actions that must be performed before non-administrative users can work with spatial data. If you are an administrative user of Spatial Studio, you must:

  • Download the Oracle Spatial Studio application from Oracle Technical Resources (formerly called Oracle Technology Network) and install it.
  • Set up a database schema to be the Spatial Studio schema, that is, to hold metadata for Spatial Studio.

    The Spatial Studio schema can be either an existing database schema in which Spatial Studio metadata will be added, or a newly created schema that will be used only for Spatial Studio.

  • Configure the newly installed Spatial Studio application.

    When the installation and configuration actions are completed, users can connect to the database, start Spatial Studio, and use its features.

Note:

The Spatial Studio application can be downloaded in either of the following formats:
  • Quick Start: A ready-to-run standalone application packaged in a zip file containing what you need to launch the Spatial Studio web application on your desktop. (You will still need to have JDK 8 64-bit, update 181 or later installed on your desktop, because no Java kit is bundled with this kit.)

    Quick Start is well suited for personal and development use.

  • A WLS-optimized EAR (Enterprise Application aRchive) file. This .ear file can be deployed to an existing WebLogic Server domain administered by an organization's WLS or middleware administrator.

    This is the recommended installation and deployment method if you intend for multiple end users to access the same Spatial Studio web application.

A given person or database user can be both an administrative user and a non-administrative user, or can be only an administrative user or a non-administrative user.

2.1 Prerequisites and Recommendations for Spatial Studio

Some prerequisites and recommendations apply for using Spatial Studio.

Oracle Spatial and Graph must be installed on the database to which any users will connect to perform actions with Spatial Studio. (It is not sufficient to have only Oracle Locator installed.)

The following additional requirements and recommendations apply:
  • Java 8 64-bit, update 181 or later. Note that newer versions of Java (such as Java 9 or higher) have not been tested, and older versions are not supported.
  • Oracle Database 12.2 or later. This applies both to the Spatial Studio metadata schema and to all database connections that will be used by Spatial Studio users.
  • At least the following privileges for each database user that works with Spatial Studio:
    create session, connect, resource, create view, create sequence,
    create synonym, create procedure, query rewrite
  • Quota on the default tablespace for each database user that works with Spatial Studio. ALTER USER statement format: ALTER USER [username] QUOTA [quota value] ON [default tablespace name];

    For example, for a user named test_user with default tablespace users: 

    ALTER USER test_user QUOTA unlimited ON users;
  • The default tablespace for the Spatial Studio repository schema should not use compression.

Parent topic: Administering Oracle Spatial Studio

2.2 Downloading and Installing Spatial Studio

Spatial Studio must be downloaded and installed before anyone can use it to perform interesting work on spatial data.

Go to https://www.oracle.com/database/technologies/spatialandgraph.html and find the instructions for downloading and installing Spatial Studio.

Parent topic: Administering Oracle Spatial Studio

2.2.1 Installing and Configuring the Spatial Studio Quick Start

Quick Start is an easy method for getting started, and is well suited for personal and development use.

The Quick Start is packaged in a single zip that contains everything you need to start using Spatial Studio, except for Java 8 (64-bit, update 181 or later) and your own database schemas.

The following are general steps for getting started:

  1. Download the Quick Start zip archive OracleSpatialStudio_qs.zip.
  2. Unzip (extract) it, which results in a directory named Oracle_Spatial_Studio.
  3. Ensure that the JAVA_HOME environment variable exists on your system, and points to a full JDK installation of Java SE Development Kit 8u181 (64-bit) or later.
  4. Ensure that the ports 8080 and 4040 are not being used by any other (web) applications. (You can direct Spatial Studio to use different ports, but 8080 and 4040 are the default.) Port 8080 is to used with the http:// protocol, while port 4040 is for the https:// protocol.

    Note that by default, Spatial Studio only allows access using https.

  5. From a command window (Windows) or terminal (Linux or Mac), go to (cd) the Oracle_Spatial_Studio directory. This directory contains several .bat or .sh files.
  6. Use start.sh or start.bat to start the application. (On Linux or Mac you may need to ensure that the .sh files are executable by first running the command: chmod u+x *.sh)

    Leave the terminal or command window open.

  7. In your browser, go to the URL: https://localhost:4040/spatialstudio

    The default admin user login credentials are admin/welcome1. It is strongly recommended that you immediately change the password.

    The admin user's and the two built-in regular users’ passwords are all stored in encrypted form. For how to change the (encrypted) password of a Spatial Studio user, see the README file for the Quick Start.

Note:

The following considerations apply to using the Quick Start:

  • The default port is 4040, but you can change it by editing the file conf/server.json in Oracle_Spatial_Studio. You will need to restart the application after you make any change. (The same applies if you change the HTTP port value from the default 8080.)
  • The Quick Start provides several predefined web user login accounts named admin, manager, author, consumer, and limited. These users and their login passwords are defined in the configuration file conf/jetty-realm.properties. You should change the passwords immediately after you unzip the downloaded Quick Start kit.

    Because the Quick Start is intended for personal use, the passwords for the end user accounts are not encrypted. However, all other passwords, such as those used to log into the Spatial Studio metadata schema or for any user-created connections to database schemas, are strongly encrypted everywhere.

  • To stop the application, the preferred approach is to start a second terminal or command window, then go to the same Oracle_Spatial_Studio folder and run the stop.bat or stop.sh script.

Parent topic: Downloading and Installing Spatial Studio

2.2.2 Installing Spatial Studio to a WebLogic Server Domain

Spatial Studio can be deployed to a WebLogic Server domain, the recommended approach if multiple end users will access the same Spatial Studio application.

Note:

For the initial release of Spatial Studio, it is recommended that you deploy the Spatial Studio EAR archive (downloaded from Oracle Technical Resources) to only a single managed server in your WLS domain. In other words, you should avoid deploying Spatial Studio to a cluster with more than one managed server in it, to avoid potential cached Spatial Studio metadata becoming out of sync between the managed servers. (This limitation may be removed in a future release of Spatial Studio.)

The general approach for deploying Spatial Studio to WebLogic Server is no different from deploying any other Java EE EAR application. The easiest way to do so is by using the WebLogic Server’s Admin console with the following steps. Note that in all or most steps you can accept the default values provided by the WLS Installation Application Wizard.

  1. Download the Studio EAR archive from Oracle Technical Resources or eDelivery, and save it to your local system.
  2. Log into the target WLS domain’s Admin console.
  3. Click the Deployments link on the left side.
  4. Click Install button under the Deployments section, as shown in the following figure (note that the exact contents may be different for your instance of WLS).

    Figure 2-1 WLS Admin Console for Deploying Spatial Studio

    Description of Figure 2-1 follows
    Description of "Figure 2-1 WLS Admin Console for Deploying Spatial Studio"
  5. On the next page, , select the Spatial Studio EAR file downloaded previously, and install it as an application (not as a library).
  6. Click through the remaining steps, including selecting the proper target server. You should accept the default options in all cases unless you know exactly what you are doing. Finally, click Save to complete the deployment.
  7. If your WLS runs in production mode, you may need to activate the changes to ensure the deployment is activated.
  8. Make sure the newly deployed Spatial Studio application is marked Active; otherwise, you may need to explicitly start it from the WLS administrative console.
  9. Access the Studio application using your managed server’s URL with the /spatialstudio context root. For example: http://mycompany.com:7002/spatialstudio

Parent topic: Downloading and Installing Spatial Studio

2.2.2.1 Preventing a Spatial Studio Admin User from General WLS Administration

If you want to prevent a Spatial Studio administrative user from performing other general WebLogic Server administrative operations, follow the instructions in this topic.

The Spatial Studio application by default allows all WebLogic managed admin users (those who are in WebLogic’s Administrators group) to log into the Spatial Studio application and assume Admin role inside the Spatial Studio application as well.

However, in some scenarios, your organization may not want to provide the WebLogic Server admin account information to the user(s) that will be administering only the Spatial Studio application. In such cases, the WLS system administrator can create a new WLS group with the id value of “SGTech_SystemAdmin” in the default WLS security realm. Then, either create a new user or assign an existing non-WLS-admin user to this group. From then on, this user will assume the admin role of the Spatial Studio whenever logged in, but will not be able to administrate the WLS server in general.

Note that all WLS managed users will be able to log into Spatial Studio by default, but they will be limited to accessing only their own Spatial Studio objects such as connections, datasets, and projects. Administrative users of Spatial Studio will have full access to every Spatial Studio object created by everyone.

2.3 Setting Up the Spatial Studio Metadata Schema

You must set up a database schema to be the Spatial Studio schema, which will hold metadata used by the Spatial Studio application.

The Spatial Studio schema can be either an existing database schema in which Spatial Studio metadata will be added, or a newly created schema that will be used only for Spatial Studio. The recommended practice is to create a new database user that will be used only by Spatial Studio. The database user for the Spatial Studio schema must have the following privileges:

  • CONNECT
  • RESOURCE
  • CREATE VIEW
  • CREATE SEQUENCE
  • CREATE SYNONYM
  • CREATE PROCEDURE
  • QUERY REWRITE
  • CREATE SESSION

For example, when connected as a user with DBA privileges:

SQL> create user SPATIAL_STUDIO identified by <password>;
SQL> grant create session, connect, resource, create view, create sequence, create synonym, create procedure, query rewrite to SPATIAL_STUDIO;

When the Spatial Studio application starts running for the first time, it will generate a configuration file in a folder named .sgtech under the current user’s operating system home folder. The configuration file is named sgtech_config.json. This is where Spatial Studio application will be obtaining and storing the connection details in its metadata schema.

After the connection to the metadata schema is established, the Spatial Studio application will automatically check if the required tables and other database objects are already present, and if their versions are up to date with the latest Spatial Studio application software. If these tables are not found, or if the tables require migration, the Spatial Studio application will run the necessary SQL scripts to create or migrate them, all without any intervention from the user.

The Spatial Studio schema will contain the following tables and views:

  • SGTECH_OBJECT: stores all the domain objects for Spatial Studio.
  • SGTECH_SYS_TYPE: defines all the known types of domain objects of Spatial Studio.
  • SGTECH_SYS_JSON_SCHEMA: stores JSON data schema.
  • SGTECH_TASK_QUEUE: stores long-running jobs of Spatial Studio.
  • SGTECH_TASK_BROKER: stores job brokers for Spatial Studio.

Note:

Do not add, delete, or edit any of the Spatial Studio tables or views or the data within them. They are automatically maintained by Spatial Studio, and should not be modified by users unless directed by Oracle Support.

Parent topic: Administering Oracle Spatial Studio

2.4 Connection Requirements for Database Users of Spatial Studio

Individuals who analyze spatial data or create spatial applications will want to be able to use Spatial Studio after the tool has been installed.

Each such individual will need to connect as a database user that is authorized to run Spatial Studio. For each such database user, you as the Spatial Studio administrator must enable such access.

You can create new database users specifically for Spatial Studio access, or you can modify existing database users to enable Spatial Studio access, or you can do a combination of these approaches. Some examples, when connected as a user with DBA privileges:

SQL> create user SPATIAL_STUDIO_USER1 identified by <password>;
SQL> grant create session, connect, resource, create view, create sequence,
    create synonym, create procedure, query rewrite to SPATIAL_STUDIO_USER1;
-- and/or ...
SQL> alter user SCOTT grant create session, connect, resource, create view, create sequence,
    create synonym, create procedure, query rewrite;

In addition, each database user that works with Spatial Studio must have quota on its default tablespace, as explained in Prerequisites and Recommendations for Spatial Studio.

Parent topic: Administering Oracle Spatial Studio

2.5 Changing the Configuration Using the sgtech_config.json File

By default, Spatial Studio will create (if it does not already exist) and use a JSON file named sgtech_config.json for most of its essential configuration information.

This file is typically found in the operating system user’s home directory, in a subfolder named .sgtech. This is true whether you deployed the Studio EAR to a WebLogic domain or are just using the Quick Start.

The following topics describe some important properties in the configuration file that a system administrator should be aware of.

Parent topic: Administering Oracle Spatial Studio

2.5.1 Allow HTTPS-ONLY Access

One of the top level properties in the sgtech_config.json config file is https_only. When this value is set to true (the default), Oracle Spatial Studio will actively monitor all incoming requests and only allow requests that were made using SSL. Normal http:// requests will be denied.

Thus, if you tried to access the Spatial Studio application using an http:// URL such as http://localhost:8080/spatialstudio, and if the value of https_only is set to true, then you will not be able to log in. In fact, you will not even see the login page itself, because none of the page resources will be accessible by your browser. Similarly, all RESTful requests will be blocked unless accessed using HTTPS.

If your environment (such as WebLogic Server) supports only http access, then you can change the value of https_only to false, and make sure to restart the Spatial Studio application or the JavaEE container where Spatial Studio is deployed.

Parent topic: Changing the Configuration Using the sgtech_config.json File

2.5.2 Connecting to the Spatial Studio Metadata Schema

Spatial Studio must have access to a set of metadata tables, such as SGTECH_OBJECT. These tables are collectively considered the repository of the Spatial Studio application. The database schema that hosts these tables is considered the metadata schema or repository schema of Spatial Studio.

Spatial Studio must be able to establish a connection to this metadata schema as the first step during startup, when the connection details are found in the sgtech_config.json file in the metadata_schema section.

In an emergency situation, you can also manually edit this section to change or correct the connection details. However, be careful whenever editing this file, because any syntax error can cause Spatial Studio to stop working or fail to restart.

When you manually enter the repository schema connection details in the sgtech_config.json file (in the metadata_schema section), you must first specify whether CONTAINER or SPATAL_STUDIO is managing the physical JDBC connections: 

“metadata_schema” : {
    “connection_manager”: “CONTAINER”
}

Or

“metadata_schema” : {
    “connection_manager”: “SPATIAL_STUDIO”
}

When connection_manager is set to CONTAINER, it means the JDBC connections to the Spatial Studio’s repository schema are managed through a Java EE data source already created in Jetty (for Quick Start) or WebLogic Server. For example, if there is a data source named jdbc/studioMetadata in the WLS domain, and if you want Studio to connect to the target schema using this data source, the relevant section in sgtech_config.json should look like this: 

“metadata_schema” {
“connection_manager” : “CONTAINER”,
"container_managed":{
        “jndi_datasource_name” : “jdbc/studioMetadata”
}
}

Note:

As of Spatial Studio Release 19.2, you cannot enter the container-managed connection details in the Spatial Studio application, so manually editing sgtech_config.json file is the only supported approach.

However, if you want Spatial Studio to manage the physical connections to its metadata schema, set connection_manager to SPATIAL_STUDIO, and supply the full set of JDBC connection details, which vary depending on whether the schema resides in an Oracle Autonomous database (which requires a database Wallet for establishing connections), or a regular database on-premises. You can check the inline comments inside the sgtech_config.json file for more details, but it is best if you simply log onto Spatial Studio as an admin user and then interactively supply the connection details for the repository schema. Such details will then be automatically saved in sgtech_config.json after Spatial Studio verifies the connection.

Parent topic: Changing the Configuration Using the sgtech_config.json File

2.5.3 Caching Metadata Objects

During run time as users create connections, datasets, and projects, Spatial Studio is creating, modifying, and storing a large amount of metadata (sometimes called Spatial Studio’s "domain objects"), such as the definition of a dataset and all of its columns, or the definition of a project including the full layout of all of its visualizations.

All the metadata objects are permanently stored in the metadata table SGTECH_OBJECT, but if the database must be accessed frequently (such as every time you open a project or view the properties of a dataset), performance may suffer. If this occurs, the solution is to cache frequently accessed copies of such metadata objects in memory.

The cache section of the sgtech_config.json file lets you specify whether to enable such an in-memory cache of metadata objects. If the cache is enabled, then you can further specify how many such objects can be cached and for how long. A general rule is that max_size (the maximum number of metadata objects to be cached) should be no less than 1000, but probably should not exceed 10000 unless you have a very large amount of memory allocated to Spatial Studio.

Parent topic: Changing the Configuration Using the sgtech_config.json File