Help - Caris

Transcription

Help - Caris

CARIS Spatial Fusion Enterprise 5.9 Viewer
Reference Guide
Teledyne CARIS
(Global Headquarters)
115 Waggoners Lane
Fredericton, NB
Canada
E3B 2L4
Teledyne CARIS EMEA
Bremvallei 1
5237 LV 's-Hertogenbosch
The Netherlands
Phone: 1 (506) 458-8533
(English/French/Spanish)
Fax: 1 (506) 459-3849
Email: [email protected]
Assistance: [email protected]
Web site: www.teledynecaris.com
Phone: +31 (0)73 648 8888
Fax: +31 (0)73 648 8889
Assistance: [email protected]
Teledyne CARIS USA
415 N. Alfred Street
Alexandria, VA
United States
22314
Teledyne CARIS Asia Pacific
PO Box 1580
Milton QLD 4064
AUSTRALIA
Phone: 1 (703) 299-9712
Fax: 1 (703) 299-9715
Phone: +61 (0) 7 3719 5132
June 2016
Trademarks owned by CARIS
The legally binding version of this Trademark and Copyright Statement is solely the English version. Only the
English version is decisive for the content of this Trademark and Copyright Statement and the rights and duties
arising from it. Versions in other languages are non-binding translations which are merely for information
purposes.
This is a listing of USPTO-registered trademarks and trademarks owned by Universal Systems Ltd.
doing business as CARIS ("CARIS") and might also be trademarks or registered trademarks in other
countries. Please note that laws concerning use and marking of trademarks or product names vary by
country. Consult a local attorney for additional guidance. CARIS permits the use of its trademarks and
registered trademarks only where they are used in reference to CARIS and its products, the markings
used are appropriate to the country or countries of publication, and CARIS is explicitly acknowledged
as the owner of the mark. CARIS reserves the right to withdraw this permission at its sole discretion
for any use it feels is inappropriate or adverse to its interests. CARIS otherwise prohibits the use of any
of its registered symbols, insignia, or other identifying marks without express written approval.
Violations are subject to liability for damages, injunctive relief, attorney's fees and other penalties.
Not all trademarks used by CARIS are listed in this document. Failure of a mark to appear on this page
does not mean that CARIS does not use the mark nor does it mean that the product is not actively
marketed or is not significant within its relevant market. The absence of a product or service name or
logo from this list or the absence of a TM or TM Reg. USPTO notation against a product or phrase listed
below does not constitute a waiver by CARIS of its trademark or other intellectual property rights
concerning that name or logo.
The following are trademarks or USPTO-registered trademarks of CARIS:
•
•
•
•
•
•
•
•
•
•
•
•
•
Article 76 Module
Bathy DataBASE
Bathy DataBASE Server
BASE Editor
BASE Manager
BDB
CARIS
CARIS GIS
CARIS Notebook
CARIS Onboard
ChartServer
CPD
Core Production Database
•
•
•
•
•
•
•
•
•
•
•
Easy View
EAM
Engineering Analysis Module
HIPS
HPD
HPD Server
Hydrographic Production
Database
Limits and Boundaries
Module
LIN
LOTS
LOTS Browser
•
•
•
•
•
•
•
•
•
•
•
•
•
LOTS Limits and Boundaries
LOTS Article 76
One Feature, One Time
Paper Chart Composer
Paper Chart Editor
Ping-to-Chart
Product Editor
Publications Module
S-57 Composer
SIPS
Source Editor
Spatial Fusion
Spatial Fusion Enterprise
Those trademarks followed by or footnoted as TM Reg. USPTO later in this document are registered
trademarks of CARIS in the United States; those followed by or footnoted as TM Reg. CIPO are registered
trademarks of CARIS in Canada; those followed by or footnoted as either TM Reg. USPTO and CIPO or
TM Reg. USPTO, CIPO
are registered trademarks of CARIS in both the United States and Canada; those
followed by or footnoted as TM are trademarks or common law marks of CARIS in Canada and the
United States, and in other countries.
The trademarks and names of other companies and products mentioned herein are the property of
their respective owners.
Copyright owned by CARIS
All written and image content in this document not protected by the copyrights of others is © Copyright
2004, CARIS. All rights reserved. All reproduction and redistribution is strictly prohibited without the
express prior written consent of CARIS.
Copyright © 2016 CARIS. All rights reserved.
Table of Contents
1
About the Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2
Deployment Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3
Java Runtime Environment . . . . . . . . . . . . . . . . . . . . . . . 25
4
Apache Tomcat. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5
What is the Viewer? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Spatial Fusion Viewer Requirements . . . . . . . . . . . . . . . . . . . . .
Installation Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Obtain Installation Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Terms Used in this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Install JRE 8.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Install Tomcat 8.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deploy the Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10
12
13
16
17
20
21
22
23
Java Runtime Environment 8.0. . . . . . . . . . . . . . . . . . . . . . . . . . 26
JRE Deployment File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Deploy JRE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Apache Tomcat 8.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tomcat Installation File . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Install Apache Tomcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configure Tomcat Java Options . . . . . . . . . . . . . . . . . . . . . . . . .
Location of Java Virtual Machine . . . . . . . . . . . . . . . . . . . . . .
Custom Windows Service Name . . . . . . . . . . . . . . . . . . . . . .
Java Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Edit Tomcat Java Options . . . . . . . . . . . . . . . . . . . . . . . . . . .
Further Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Start and Stop Tomcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
30
30
30
31
41
41
41
42
45
48
49
Spatial Fusion Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Preparing to Deploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deployment and Documentation Files . . . . . . . . . . . . . . . . . .
Web Archive Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deploy the Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Launch the Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . .
52
52
52
53
55
56
5
6
6
Basics of the Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
7
Map Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Opening the Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Interface Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Changing the Appearance of the Web Application. . . . . . . . . 66
Data Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Add Data Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Edit Data Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Delete Data Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Points of Interest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Where and how to get POI connection URLs. . . . . . . . . . . . .
Using Photo and Video web feeds for POIs . . . . . . . . . . . . . .
Using a WFS to display POIs . . . . . . . . . . . . . . . . . . . . . . . . .
Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Google Maps API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Add Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Edit Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Delete Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
70
70
72
74
76
79
80
85
86
86
87
98
99
8
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
9
General Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Add/Edit Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Delete Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Add Roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Edit Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Delete Roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Regain Access to your Account . . . . . . . . . . . . . . . . . . . . . . . .
LDAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enable LDAP Authentication . . . . . . . . . . . . . . . . . . . . . . . .
Use LDAP Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . .
Disable LDAP Authentication . . . . . . . . . . . . . . . . . . . . . . . .
Default Language Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
102
102
105
106
107
109
110
111
113
115
116
120
122
124
126
127
127
129
131
A
Advanced Configuration Settings . . . . . . . . . . . . . . . . 133
B
Monitor User Connections . . . . . . . . . . . . . . . . . . . . . . 147
C
Web Services Optimization . . . . . . . . . . . . . . . . . . . . . . 151
Configuration Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Apache Web Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Apache Tomcat. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Web Robots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Secure Sockets Layer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
134
135
137
142
143
Tracking users in Apache HTTPD Server . . . . . . . . . . . . . . . . . 148
View active sessions using Apache Tomcat . . . . . . . . . . . . . . . 149
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Optimization Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring Data Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Minimize Calls to Data Source . . . . . . . . . . . . . . . . . . . . . . .
Configuring Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
152
153
154
154
156
7
8
1
About the Installation
In this chapter...
WHAT IS THE VIEWER? ................................................. 10
SPATIAL FUSION VIEWER REQUIREMENTS ......................... 12
INSTALLATION NOTES .................................................... 13
OBTAIN INSTALLATION FILES........................................... 16
TERMS USED IN THIS GUIDE........................................... 17
About the Installation: What is the Viewer?
What is the Viewer?
CARIS1 Spatial Fusion2 Enterprise™ Viewer is a tool for
displaying geospatial data over the Internet or a local network
using standard Web browsers (such as Mozilla Firefox or
Microsoft Internet Explorer).
The the web application is controlled by the Viewer Manager.
With the Viewer Manager you can:
• Create data connections to the following services:
• Web Map Service (WMS),
• Web Map Tile Service (WMTS),
• Web Feature Service (WFS), and
•
Web Coverage Service (WCS).
• Create points of interest using:
• Keyhole Markup Language (KML), or
• GeoRSS_SIMPLE.
• Create themes using the layers in data connections.
• Create users and roles, and assign roles to users.
• Define settings for the web application.
• View application and service logs for the web application.
• Update the web application license.
The following diagram shows the relationship between Spatial
Fusion Server and Spatial Fusion Viewer
1. This term is a trademark of CARIS (Universal Systems Ltd.), Reg. USPTO & CIPO.
2. This term is a trademark of CARIS (Universal Systems Ltd.), Reg. USPTO.
10
CARIS Spatial Fusion Viewer Reference Guide
About the Installation: What is the Viewer?
The following diagram shows the various data formats that can
be used in the web application.
11
About the Installation: Spatial Fusion Viewer Requirements
Spatial Fusion Viewer Requirements
Before you install Spatial Fusion Viewer (the web application),
your computer must meet or exceed the following minimum
system requirements:
• Operating System: Windows Server 2008 Release 2 or
Windows Server 2012.
• Processor: 1.4 GHz or better (x64 processor)
• Memory: 2 GB of RAM or more
• Software:
• Apache Tomcat 8.0 as of SFE Viewer version 5.8.12 and
higher (Previous versions require Apache Tomcat 7.0)
• Java Runtime Environment 8.0
Geospatial data processing can be intensive. There are many
factors that can affect server response time. Some strategies for
improving response time include:
• Install Spatial Fusion Server, Spatial Fusion Viewer, Bathy
DataBASE1 and its database (Oracle or PostgreSQL)
separately on dedicated hardware to distribute the network
load.
• A network speed of 1 GBit/s or higher will reduce any input/
output constrictions and improve speed.
• Multiple instances of Tomcat can be effective in improving
response time. Further suggestions for improving response
time are described in “CONFIGURATION DATABASE” ON PAGE 134".
1. This term is a trademark of CARIS (Universal Systems Ltd.), Reg. USPTO.
12
About the Installation: Installation Notes
Installation Notes
The web application can reside on the same computer on which
Spatial Fusion Server is installed. If server response time
becomes an issue, the two applications can also be installed on
separate Java VM instances or even separate systems.
The applications listed below are required for a complete
installation. It is important to select the correct version of the
Java Runtime Environment (Server JRE bundle).
CARIS recommends that the applications are installed in the
sequence shown below:
Sequence
Software
Configuration Notes
1
Java Runtime
Environment
(Server JRE
bundle) 1.8
The Server JRE bundle should be used. Version
1.8 is also known as version 8.0.
2
Apache Tomcat
8.0
3
Spatial Fusion
Viewer
Each one of these applications is installed separately.
All three applications can be installed by downloading the
installation files from their respective web sites.
The web application is contained in a web application archive
file (WAR).
There are two downloads available from CARIS:
• Spatial Fusion Viewer 5.9 WAR
• Documentation zip file updated for the release (optional)
The downloads are available after logging in to this page:
http://support.caris.com
The web application can be installed by copying a downloaded
WAR to the appBase directory. By default, the appBase directory
is the [Tomcat installation directory]\webapps directory. See
“TOMCAT INSTALLATION DIRECTORY” ON PAGE 17 for more information.
There are special requirements for copying this file that must be
observed. For more information about these requirements see
“SPATIAL FUSION VIEWER” ON PAGE 51.
The web application WAR is normally renamed spatialfusionviewer.war
to prevent a different URL for each update to the WAR.
13
The web sites below will have the latest versions of the software
needed to deploy the web application:
Software
Web link
JRE (Server JRE
bundle only)
http://www.oracle.com/technetwork/java/javase/downloads/serverjre8-downloads-2133154.html
Apache Tomcat
http://tomcat.apache.org/download-80.cgi
Spatial Fusion Viewer http://support.caris.com
The following minimum versions of Java Runtime and Apache Tomcat are
recommended:
JRE 8.0 or higher
Tomcat 8.0 or higher
Configuration Options
If you are updating from an earlier version of the web
application, system administrators may wish to update the
installed version of Java Runtime Environment and Apache
Tomcat to take advantage of possible bug fixes or enhancements.
Reference to these web sites is made in the appropriate sections
of this guide.
Administrators may need to make configuration changes to
make the installation of the web application run effectively.
Factors such as other applications, connection speed, amount of
data, hardware limitations, and the number of instances of
Spatial Fusion Server and Viewer all affect how the software
should be configured.
Administrators are encouraged to use all the guides for the
software to optimize their installations.
14
Initial Installation
The installed location for the application has the following
structure:
http://localhost:8080/spatialfusionviewer/
Unless this value is modified during the installation, the default
Hypertext Transfer Protocol (HTTP) port to which Apache
Tomcat’s HTTP connector is bound is 8080.
The default account setup for the web application includes only
one account:
Update an Existing
Installation
Module
Username
Password
Spatial Fusion Viewer
admin
password
If you have data connections configured, the configuration files
can be backed up if desired before removing the applications.
Data locations are described in “DATA STORAGE LOCATIONS” ON PAGE 43.
In version 5.7.4 and higher, an option in the Tomcat Java
settings can be used to define a data directory specifically for the
web application. Defining a dedicated directory will make
backups and software updates simpler. Setting a data directory
is described in “CONFIGURE TOMCAT JAVA OPTIONS” ON PAGE 41, especially
“CUSTOM DATA DIRECTORY” ON PAGE 44.
15
About the Installation: Obtain Installation Files
Obtain Installation Files
For a complete installation, the applications listed in the table
below are required. They should be installed in this sequence on
the host computer.
The sequence is described below:
Sequence
Software
Website for Installation File
1
Java Runtime Environment
(Server JRE bundle) 8.0 (also
known as 1.8)
http://www.oracle.com/technetwork/java/javase/downloads/
server-jre8-downloads-2133154.html
2
Apache Tomcat 8.0
3
Spatial Fusion Viewer and
documentation file
http://support.caris.com
Obtain the 64-bit Windows version of the .tar.gz file.
Each one of these applications is installed separately.
16
About the Installation: Terms Used in this Guide
Terms Used in this Guide
JRE Deployment
Directory
The Java Runtime Environment (JRE) Deployment Directory is
the location in which JRE is deployed. The JRE Deployment
Directory is the directory that contains the bin and lib
directories of the JRE distribution.
The use of a compressed archive distribution to install JRE is
described in this guide. If the JRE distribution is version 8
update 5 and the compressed archive is decompressed directly to
C:\JRE
The JRE Deployment Directory would be similar to:
C:\JRE\jdk1.8.0_40\jre
If the JRE_HOME environment variable is set it should have
the same value as the JRE Deployment Directory. See “SET
JRE_HOME VARIABLE” ON PAGE 138 for instructions on how to create
this environment variable.
SFViewer Data
Directory
The SFViewer data directory is the location in which the web
application will store cached data, configuration data and files
related to metadata. The default location of the directory is the
temporary directory ("temp") used by Tomcat. The location can
be configured using the com.caris.sfv.dir Java option, for
example:
-Dcom.caris.sfv.dir=C:\Tomcat_SFViewer_data
See “CONFIGURE TOMCAT JAVA OPTIONS” ON PAGE 41 for more information.
Tomcat Installation
Directory
The Tomcat Installation Directory is the location in which
Tomcat is installed. When using the Windows installer
distribution of Tomcat, the default location will be
C:\Program Files\Apache Software Foundation\Tomcat 8.0
This can be changed during installation. There are other
methods of installing Tomcat and different configurations that
can be used. The installation directory can vary as a result.
Web Application
"The web application" means Spatial Fusion Viewer in this
guide.
17
About the Installation: Terms Used in this Guide
18
2
Deployment Overview
In this chapter...
INTRODUCTION ............................................................. 20
INSTALL JRE 8.0 ........................................................ 21
INSTALL TOMCAT 8.0 .................................................... 22
DEPLOY THE WEB APPLICATION ..................................... 23
Deployment Overview: Introduction
Introduction
This topic describes the installation process for the following
applications:
• Java Runtime Environment (Server JRE bundle) 8.0
• Tomcat 8.0
• Spatial Fusion Viewer 5.9
It is assumed that none of the software applications is installed on the target
machine.
If you are updating your installation, you should refer to the following topics:
“JAVA RUNTIME ENVIRONMENT” ON PAGE 25
“APACHE TOMCAT” ON PAGE 29
20
Deployment Overview: Install JRE 8.0
Install JRE 8.0
This section describes the deployment of Java Runtime
Environment 8.0 (Server JRE bundle).
Spatial Fusion Viewer is expected to work with JRE 7.0. However, it is tested
with JRE 8.0 so CARIS recommends JRE 8.0 in deployments of the web
application.
To install the JRE:
1. Obtain the Server JRE bundle tar.gz file. See “OBTAIN INSTALLATION FILES”
ON PAGE 16 for more information.
2. Follow the instructions for unpacking the tar.gz file, located at http://
docs.oracle.com/javase/8/docs/technotes/guides/install/
windows_server_jre.html#A1097054
You may need to unzip the tar.gz file twice on a Windows operating system to
unpack the files, first to create a .tar file, and then to extract the uncompressed
files and directories.
3. Make note of the JRE Deployment Directory. See “JRE DEPLOYMENT
DIRECTORY” ON PAGE 17 for more information.
21
Deployment Overview: Install Tomcat 8.0
Install Tomcat 8.0
To install Tomcat 8.0 using the Windows Service Installer
distribution:
1. Obtain the installation program. See “OBTAIN INSTALLATION FILES” ON
PAGE 16 for more information.
2. Double-click the installer and follow the instructions that appear on the
screen.
See “APACHE TOMCAT” ON PAGE 29 for more information.
When asked for the Java Virtual Machine path (see “JVM DIALOG BOX”
PAGE 37) type the JRE Deployment Directory (see “JRE DEPLOYMENT
DIRECTORY” ON PAGE 17).
ON
3. Stop Tomcat, if it is running.
4. Open the Tomcat configuration utility.
5. Customize the Java Options to your needs.
For more information on this step, see “CONFIGURE TOMCAT JAVA
OPTIONS” ON PAGE 41.
6. Close the Tomcat configuration utility.
22
Deployment Overview: Deploy the Web Application
Deploy the Web Application
For more explanation on WARs and deployment of them, see
“WEB ARCHIVE FILES” ON PAGE 53.
1. Ensure Tomcat has been started.
2. [Optional] Change the file name of the WAR.
Renaming the WAR will change the context name of the
application, which may be necessary in the URL. See “WEB
ARCHIVE FILES” ON PAGE 53 or “LAUNCH THE WEB APPLICATION” ON PAGE 56
for more information. If you wish to change the context name
you should do so before copying the WAR to the webapps
folder (as described in step 3).
3. Deploy the WAR, by copying it to the webapps sub-directory.
When a WAR is copied to the webapps directory it is deployed
by Tomcat. You will notice a directory is created that
corresponds to the WAR. The application is deployed in this
directory. This can take a few minutes to complete.
The deployment of the web application is now complete.
Access the Web
Application
To launch the web application type its URL in the address bar of
your browser. The URL will depend on your system
configuration. In many situations, the URL could be similar to
one of the following:
http://www.example.com/
http://www.example.com:8080/spatialfusionviewer
See “WEB ARCHIVE FILES” ON PAGE 53 or “LAUNCH THE WEB APPLICATION” ON
4. The web application should start and you should see the login page.
23
Deployment Overview: Deploy the Web Application
The default admin account login details are:
• Username: admin
• Password: password
24
3
Java Runtime Environment
In this chapter...
JAVA RUNTIME ENVIRONMENT 8.0 .................................. 26
JRE DEPLOYMENT FILE................................................ 27
DEPLOY JRE.............................................................. 28
Java Runtime Environment: Java Runtime Environment 8.0
Java Runtime Environment 8.0
Version of JRE
This section describes the deployment of Java Runtime
Environment 8.0 (Server JRE bundle).
Spatial Fusion Viewer is expected to work with JRE 7.0. However, it is tested
with JRE 8.0 so CARIS recommends JRE 8.0 in deployments of the web
application.
System administrators are advised to keep JRE up-to-date. The
website for the JRE may be helpful in providing information to
assist system administrators in making the decision on the
importance of updating the JRE.
http://www.java.com/en/download/help/index.xml
At time of writing, Java 8.0 release notes were available at this
location:
http://www.java.com/en/download/faq/release_changes.xml
or by searching the Oracle website for release notes for JRE at:
http://www.oracle.com
If Apache Tomcat has already been installed, it must be stopped before JRE is
installed or updated. If this step is not taken, Apache Tomcat will frequently fail
to start properly. See “START AND STOP TOMCAT” ON PAGE 49
If JRE has already been installed or uninstalled with Tomcat running, an
installation problem can be created. To resolve the situation, follow these steps:
1. Stop Tomcat.
2. Install the JRE.
3. Uninstall the JRE.
4. Reboot.
5. Install the JRE.
6. Start Tomcat.
For further information on starting and stopping Tomcat, see “START
TOMCAT” ON PAGE 49.
26
AND
STOP
Java Runtime Environment: JRE Deployment File
JRE Deployment File
The Windows tar.gz file for Java Runtime Environment (server JRE
bundle) can be downloaded from this web page: http://
www.oracle.com/technetwork/java/javase/downloads/server-jre8downloads-2133154.html
27
Java Runtime Environment: Deploy JRE
Deploy JRE
To deploy the JRE.
1. Use the Windows Server Control Panel > Programs and Features utility
to remove any existing installations of JRE.
2. Obtain the Server JRE bundle tar.gz file. See OBTAIN INSTALLATION FILES
16 for more information.
3. Navigate to the Windows Server Control Panel > Programs and
Features utility, and use it to remove the existing installation of JRE, if it
is there.
It is a good precaution to check whether there are any other applications using
JRE before removing it
4. Follow the instructions for unpacking the Server JRE bundle tar.gz file,
located at http://docs.oracle.com/javase/8/docs/technotes/guides/
install/windows_server_jre.html#A1097054
You may need to unzip the tar.gz file twice on a Windows operating system to
unpack the files, first to create a .tar file, and then to extract the uncompressed
files and directories.
5. Make note of the JRE Deployment Directory.
See “JRE DEPLOYMENT DIRECTORY” ON PAGE 17 for more information.
In a new installation it is necessary to install Tomcat before
deploying the web application. See “APACHE TOMCAT” ON PAGE 29 and
“SPATIAL FUSION VIEWER” ON PAGE 51 for more information.
28
4
Apache Tomcat
In this chapter...
APACHE TOMCAT 8.0.................................................... 30
INSTALL APACHE TOMCAT .............................................. 31
CONFIGURE TOMCAT JAVA OPTIONS ................................ 41
START AND STOP TOMCAT ............................................. 49
Apache Tomcat: Apache Tomcat 8.0
Apache Tomcat 8.0
Apache Tomcat 8.0 is a web server that can run the web
application.
Prerequisites
Java Runtime Environment (JRE) 8.0 must be installed before
Apache Tomcat. There will be an installation error if Tomcat
cannot locate the correct version of JRE. See “VERSION OF JRE” ON
If JRE has already been installed or uninstalled with Tomcat running, an
installation problem can be created. To resolve the situation, follow these steps:
1. Stop Tomcat.
2. Install the JRE.
4. Reboot.
5. Install the JRE.
6. Start Tomcat.
For further information on starting and stopping Tomcat, see “START
TOMCAT” ON PAGE 49.
AND
STOP
The default HTTP Port of 8080 is normally used for Apache Tomcat 8.0. If a
different port is required, the desired port settings can be made during the
installation of Apache Tomcat.
Tomcat Installation File
The Apache Tomcat 8.0 installation program can be obtained by
downloading it from the following website:
You will need the installation program before the installation
can proceed.
30
Apache Tomcat: Install Apache Tomcat
Install Apache Tomcat
Uninstall Previous
Version
If you are updating Apache Tomcat to the current version, you
will need to uninstall the previous version before installing the
new one. You may also need to shut down any open Tomcat
configuration or monitor applications (for example,
Tomcat8w.exe). Windows Server Task Manager may be required
for this process.
After Tomcat is stopped and any monitor or configuration
programs are closed, Apache Tomcat can be removed by using
the Windows Server Control Panel > Programs and Features utility
to remove the existing installation of Apache Tomcat.
During the uninstall process, you will be asked if you wish to
remove the data directories in this dialog box:
It is possible that keeping the existing files will create duplicate
sets of data, and if disk space is limited that might be a problem.
Click Yes to delete the data files or click No to retain them.
If backups are made, data can be reconfigured from them.
Install Current Version
To install Apache Tomcat:
1. Click the installation program file for Apache Tomcat 8.0.
The following dialog box is displayed.
31
2. To start installing Tomcat, click Next.
The License Agreement dialog box is displayed.
32
3. Read the agreement carefully. If you accept the terms, click I Agree
and the installation will continue. If you do not accept the terms, click
Cancel and the installation will terminate.
The Component Selection dialog box is displayed.
Expand the Tomcat section by clicking the + symbol.
33
The default values should be changed.
• Check Native
• Uncheck Documentation and Manager
Adding the Service Startup component permits Tomcat to
start as a service automatically on startup. If you do not
check this item you will always need to start Tomcat
manually after the system is rebooted.
The Manager item is not needed in most cases.
4. Check or uncheck the desired options.
5. Click Next.
The Configuration dialog box is displayed.
If you customize the Windows Service Name, the customized name results in
changes to the default names of directories containing data.
If you are migrating existing data during an upgrade of Tomcat, it is important to
check the location of data directories to ensure that the data will be placed
where Tomcat will recognize it.
The new directory names may also affect the Java settings for Tomcat. See
“CONFIGURE TOMCAT JAVA OPTIONS” ON PAGE 41 for more information.
34
If you wish to assign a port number different from the default value, you will need
to record that port number for possible further use, depending on how the
system will be integrated into the existing network.
Windows Service Name
6. Type a customized Service Name if desired.
35
7. Type port numbers that are appropriate for your system.
The default HTTP/1.1 Connector Port is 8080. This can be
changed to another available port. It is not necessary to make
a change if only one Tomcat instance will be installed. In
cases where more than one instance of Tomcat is installed,
each instance must have a unique port.
8. Type your Tomcat user name and password.
If you have installed the manager application, it is recommended that you
change the username and password at this time for security reasons. If you
forget them, they can be discovered by looking at the Tomcat\conf\tomcatusers.xml file.
9. Click Next.
36
JVM Dialog Box
The Java Virtual Machine dialog box is displayed.
10.Click Browse (“...”) and navigate to the JRE Deployment Directory.
11. Click Next.
The Install Location dialog box is displayed.
37
12.[Optional] To select a different directory for the application, click
Browse, select the directory to use and click OK.
You will need to know the location of the Tomcat installation directory for the
web application installation process.
13.Click Install.
The resulting dialog box shows the progress of the installation
process (as the application files are copied to your machine).
38
When the application files are copied, the buttons at the bottom
of the dialog box become active.
14.To continue after the files are installed, click Next.
The final dialog box of the Tomcat installation wizard is
displayed.
39
15.Uncheck the Run Tomcat check box.
You will need to modify the startup settings for Apache Tomcat to run the web
application. If Tomcat is running, it will need to be stopped and started before
the changed startup settings will become effective, and the web application can
be started.
16.To close the installation program for Apache Tomcat, click Finish.
If Tomcat has already been started, stop it before restoring the
backed up data directory. The directory location is discussed in
“DATA STORAGE LOCATIONS” ON PAGE 43.
40
Apache Tomcat: Configure Tomcat Java Options
Configure Tomcat Java Options
It is necessary to adjust the settings in Apache Tomcat so that they will be able
to run the web application properly. You do not need to stop Tomcat to type
these settings, but the new settings will not take effect until Tomcat is restarted.
Location of Java Virtual Machine
The JRE Deployment Directory must be specified correctly on
the Tomcat Java Options page, or Tomcat will not open. See “JRE
DEPLOYMENT DIRECTORY” ON PAGE 17 for more information.
Custom Windows Service Name
Before configuring the Tomcat Java Options, it is important to
verify the location of the data directory, especially if you
customized the default name for the Windows Service.
The default Tomcat data directory, often referred to as the temp
directory, is located here:
[Tomcat Installation Directory]\temp
However, the location of this directory may have been affected if
you customized the Windows Service Name during the
installation process. For example, if you called the service
“Webserver”, the location of the data directory would be:
C:\Program Files\Apache Software Foundation\Tomcat
8.0_Webserver\temp
and the Tomcat installation directory is:
C:\Program Files\Apache Software Foundation\Tomcat
8.0_Webserver\
In an installation of Tomcat, it is also possible that the default
data directory has been set to another location outside the
Tomcat directories.
As you review the Java options below you will need to ensure
that the correct directory locations are entered for both the data
directory and the Tomcat installation directory. Failure to do so
may result in problems.
41
Java Options
The Java options can be edited in a text editor, and pasted into
the Tomcat Configuration utility when complete.
The following contains sample Tomcat Java options that need to
be added to the existing default options. These options may need
to be adjusted for your situation, as discussed below.
-Xms128m
-Xmx256m
The XX:MaxPermSize setting is appropriate for earlier versions of JRE, but not
JRE 8.0. If this setting is included for JRE 8.0, it will be ignored.
These lines can be placed in a text editor, edited to match your
situation, and later placed in the Tomcat Java tab options.
These Java options have been changed from the default values
in the sample options:
Java Option
Purpose
defines a location for the web application data. Only
the web application data will be stored in this location.
-Dcom.caris.sfv.dir
The default temporary directory that applications
running within Tomcat can safely use is defined by
java.io.tmpdir (also known as the Java temp
directory). Tomcat is running in a Java process as a
certain user, and requires a directory where write
access is permitted for that user.
The folder specified by com.caris.sfv.dir will
be created if it does not exist when the web
application is deployed.
If com.caris.sfv.dir is defined, write access will
apply to the directory defined, and only the web
application data will be written to this directory.
-Xms
-Xmx
increase Tomcat memory settings to the amount
required. The web application will not function
correctly without these options. Depending on your
configuration, additional memory may be required.
• Xms = starting heap size for the Java process
that Tomcat will run in.
• Xmx = maximum heap size for the Java process
that Tomcat will run in.
These values affect the Java Virtual Machine. They
need to be increased relative to the number and size
of the applications running on a single VM instance.
42
Tomcat Memory
Settings
The default memory settings in the Java options need to be
increased. The following options are the minimum values
advisable if you are running only spatialfusionviewer.war in
Tomcat:
-Xms128m
-Xmx256m
You may need to increase these settings if you are running other
applications in Tomcat.
Java is a virtual machine, and allocates a large chunk of memory
for its heap. The heap that is allocated is used by the application
that it is running. For servlet containers (like Tomcat) multiple
applications are running and sharing the heap including Tomcat
and each web application it is running.
An increased heap size may help when two or more web
applications are running in a single Tomcat instance, since two
applications running in a single Virtual Machine takes up more
space.
These settings often depend on the system’s hardware and its
configuration.
For guidelines in optimizing resources see “WEB SERVICES OPTIMIZATION”
PAGE 151.
Data Storage Locations
ON
The com.caris.sfv.dir java settings can be used to customize
the default location of directories for storing tiles, databases, and
metadata.
• java.io.tmpdir is a Java setting for all data directories
created by Apache Tomcat. This folder is a sub-directory of
the Tomcat installation folder, and it is often referred to as
the Java temp directory.
• com.caris.sfv.dir is a Java setting for all data directories for
the web application. If it is left blank, this variable defaults to
java.io.tmpdir.
A custom Windows service name can affect data storage locations. See
“CUSTOM WINDOWS SERVICE NAME” ON PAGE 41 for details.
43
Custom Data Directory
The com.caris.sfv.dir Java option lets you to specify the
location where the web application will store its configuration
data, its WCS coverage cache, WMTS tile cache and metadata. It
can be used to specify a location outside the Tomcat Installation
Directory. Using a location outside the Tomcat Installation
Directory can be beneficial when it comes to upgrading Tomcat.
If the com.caris.sfv.dir location is not set, all Tomcat data will be stored
in the java.io.tmpdir location, and other application data can become
mixed in with the web application directories. To make backups easier to
manage, it is best to set the com.caris.sfv.dir java property to a
convenient location for storing data.
To change the location for all the web application data, add or
edit the following property in the Tomcat Java options, for
example:
See “CONFIGURE TOMCAT JAVA OPTIONS” ON PAGE 41 for more information.
It is important to know the location of com.caris.sfv.dir when
you use the procedures described in “CONFIGURE TOMCAT JAVA OPTIONS”
ON PAGE 41.
Default Tomcat Data
Directory
The web application configuration and cache data will be stored
in the Tomcat temporary directory by default. This folder is
often referred to as the Tomcat "temp" directory. The default
location of the Tomcat temporary directory is:
[Tomcat Installation Directory]\temp
The location of this directory can be controlled using the
-Djava.io.tmpdir
Java option.
You can use the -Dcom.caris.sfv.dir Java option to set a
different location for the configuration and cache data.
44
Edit Tomcat Java Options
1. Open the Apache Tomcat Properties application by clicking the Start >
All programs > Apache Tomcat 8.0 > Configure Tomcat Menu
sequence.
The following dialog box will appear:
2. Click Java.
45
3. Check and edit if necessary the location of the Java Virtual Machine.
The Java Virtual Machine is found in the JRE Deployment
Directory. Click ... and navigate to the jvm.dll that is found
in:
[JRE Deployment Directory]\bin\server\jvm.dll
4. Scroll to the bottom of the Java Options
46
5. When you have completed the edits to the Java Options, click Apply.
47
You can paste the new settings you have edited in a text editor
into the Java Options text box. Editing these options is discussed
in “CONFIGURE TOMCAT JAVA OPTIONS” ON PAGE 41.
6. Click OK.
The new options will not take effect until the next time Tomcat is started.
The Apache Tomcat installation process is complete. You can
now restore data backups to the locations you have configured,
and make any desired advanced Tomcat settings.
To deploy the web application, see “PREPARING TO DEPLOY” ON
PAGE 52.“SPATIAL FUSION VIEWER” ON PAGE 51.
Further Information
Other settings for Tomcat may also be important for your
configuration. For more information see:
• “CONFIGURATION DATABASE” ON PAGE 134
• “APACHE WEB SERVER” ON PAGE 135
• “APACHE TOMCAT” ON PAGE 137
• “WEB ROBOTS” ON PAGE 142
• “SECURE SOCKETS LAYER” ON PAGE 143
The Apache Tomcat documentation may be helpful in providing information
about configuring your installation. It is located at http://tomcat.apache.org/
tomcat-8.0-doc/
48
Apache Tomcat: Start and Stop Tomcat
Start and Stop Tomcat
You can test the Tomcat installation by starting and stopping
Apache Tomcat from Windows Server Services:
Start Tomcat
Stop Tomcat
1. Select Start > Control Panel >
1. Select Start > Control Panel >
Administrative Tools > Services > Apache
Administrative Tools > Services > Apache
Tomcat.
Tomcat.
2. Select Start—Tomcat becomes operational.
2. Select Stop—Tomcat closes.
If Tomcat is not listed in the Services menu, you may need to use one of the
following actions to cause it to appear:
• Use the Action > Refresh menu in the Services Menu to update the
display.
• Use the Start > All Programs > Apache Tomcat > Configure
Tomcat menu sequence to start Tomcat.
• Reboot your computer.
You can also use the Windows sc.exe utility to stop and start
Tomcat.
You should wait until Tomcat has finished loading before
opening any applications, which may take several minutes,
depending on the speed of your computer.
If the JRE is uninstalled while Tomcat is running, Tomcat will
often fail to start, and generate log entries such as these:
java/lang/NoClassDefFoundError
java/lang/Object
In that situation, it is best to use this sequence to resolve the
problem:
1. Stop Tomcat.
2. Install the JRE.
4. Reboot.
5. Install the JRE.
6. Start Tomcat.
See “JAVA RUNTIME ENVIRONMENT” ON PAGE 25 and “APACHE TOMCAT 8.0” ON
If the IP address initially used to register a data source becomes unavailable,
the administrator only needs to restart Tomcat for the system to automatically
re-register that data source using the next available IP address.
49
Apache Tomcat: Start and Stop Tomcat
Advanced Configuration
Settings
50
For information on advanced configuration settings, such as web
robots for Tomcat, see “ADVANCED CONFIGURATION SETTINGS” ON PAGE 133.
5
Spatial Fusion Viewer
In this chapter...
PREPARING TO DEPLOY ................................................ 52
WEB ARCHIVE FILES .................................................... 53
DEPLOY THE WEB APPLICATION ..................................... 55
LAUNCH THE WEB APPLICATION ..................................... 56
Spatial Fusion Viewer: Preparing to Deploy
Preparing to Deploy
Prerequisites
Before the web application can be deployed, the following
applications must be installed:
• Java Runtime Environment (JRE) 8.0, and
• Apache Tomcat 8.0.
JRE and Apache Tomcat should be installed before proceeding
further with the deployment of the web application. Failure to do
so will result in configuration problems.
Deployment and Documentation Files
Deployment files for the web application can be downloaded
from the CARIS Customer Support website.
The documentation is contained in a zip file that includes the
following PDF documents:
• CARIS Spatial Fusion Viewer Changes List
• CARIS Spatial Fusion Viewer Quick Start Guide This
document is useful for a test installation and is not generally
used for a production environment.
• CARIS Spatial Fusion Viewer Reference Guide
The Help link of the web application opens HTML pages that
have the same information as CARIS Spatial Fusion Viewer
Reference Guide.
52
Spatial Fusion Viewer: Web Archive Files
Web Archive Files
A WAR is a web application archive file with a file extension of
"war". It is commonly referred to as a "WAR". WARs are used by
Apache Tomcat to deploy the web application directory and its
contents.
When a WAR is placed in the Tomcat webapps directory while
Tomcat is running, Tomcat expands the archive by creating a set
of directories that contain the expanded files. The high level
directory has the same name as the WAR, for example
spatialfusionviewer for spatialfusionviewer.war. This process
starts immediately when the WAR is deployed in the Tomcat
webapps directory. It can cause configuration problems if Tomcat
is stopped or the WAR is deleted before the process of creating
the directory is complete, which can take several minutes.
Multiple WARs can be copied to different file names inside the
Tomcat webapps directory and deployed in that directory.
Tomcat responds by creating a new directory, using the file
name of the WAR for the highest level of directory. However,
configuration of Tomcat and system resources becomes very
important to consider with multiple instances of the web
application. For further information, see
• “CONFIGURE TOMCAT JAVA OPTIONS” ON PAGE 41,
• “ADVANCED CONFIGURATION SETTINGS” ON PAGE 133, and
• Apache Tomcat documentation at http://tomcat.apache.org/tomcat8.0-doc/
A WAR can also be deleted by an administrator, and Tomcat
responds by deleting the matching directory structure, a process
that can take several minutes depending on system resources
and loads. Stopping Tomcat while it is in the process of this
deletion can cause problems.
Deploying or deleting WARs while Tomcat is stopped can create problems. It is
safest to let Tomcat deploy or delete directories on its own.
If Tomcat fails to delete or deploy directories automatically, try stopping and
restarting Tomcat.
If Tomcat fails to delete directories, it may be necessary to stop Tomcat, delete
the directories manually, and restart Tomcat.
If the WAR is deployed while Tomcat is running it creates the
directories within a few minutes, but if Tomcat is stopped the
process begins when it is started. In either case, the web
application is not accessible until Tomcat has finished the
deployment of the WAR.
A WAR and its matching directory structure can be deleted
while Tomcat is stopped, if that is desired.
53
Spatial Fusion Viewer: Web Archive Files
Rename the WAR
A WAR deploys into a directory that matches the file name
portion of the WAR (also known as the context name). For
example, if the file name of the deployed WAR is
spatialfusionviewer_5.9_RC1.war, the name of the high level
directory deployed by Tomcat will be
spatialfusionviewer_5.9_RC1
which will also be the context name. When the WAR is updated,
there will be a new context, which may affect the URL and the
configuration. To prevent that situation, the WAR can be
renamed before it is deployed., for example, to
spatialfusionviewer_.war. By renaming the WAR, the context
and the high level directory deployed by Tomcat can the same for
each update, for example spatialfusionviewer_.
54
Spatial Fusion Viewer: Deploy the Web Application
Deploy the Web Application
Tomcat can be in a stopped state or running. If stopped then the
WAR is deployed at startup, if the host's deployOnStartup
attribute is set to true.
If Tomcat is running when the WAR is deployed, the host
autoDeploy attribute must be set to true.
For further information, see Apache Tomcat documentation:
https://tomcat.apache.org/tomcat-8.0-doc/deployerhowto.html#Deployment_on_Tomcat_startup
https://tomcat.apache.org/tomcat-8.0-doc/deployerhowto.html#Deploying_on_a_running_Tomcat_server
In a default installation:
1. Rename the WAR if desired.
See “RENAME THE WAR” ON PAGE 54 for more information.
2. Start Tomcat.
3. Navigate to the [Tomcat Installation Directory]\webapps subdirectory.
See “TOMCAT INSTALLATION DIRECTORY” ON PAGE 17 for more
information.
4. [Optional] If you are updating an existing web application, delete the
existing WAR, for example spatialfusionviewer.war.
Before proceeding to the next step, wait until the directory
that matches the name of the previous WAR is deleted by
Tomcat. This may take a number of minutes, depending on
the speed and load of the server.
5. Copy the new WAR to the webapps sub-directory.
Wait until the matching directory is created by Tomcat.
Tomcat will create a new directory for the WAR (for example,
spatialfusionviewer) and will deploy the contents of the new
WAR into it.
6. Open the web application, as described in “LAUNCH THE WEB APPLICATION”
ON PAGE 56.
It may take a few minutes for Tomcat to fully deploy the web
application before it can be accessed in a web browser.
If you wish to deploy multiple WARs, “ADVANCED CONFIGURATION
SETTINGS” ON PAGE 133 may contain useful information.
55
Spatial Fusion Viewer: Launch the Web Application
Launch the Web Application
Tomcat must be running before Fusion Viewer can be started.
After installation, the web application may take up to five minutes to reconnect
data connections. Until the reconnection has taken place, the open web
services will be set Offline.
To launch the web application type its URL in the address bar of
your browser. The URL will depend on your system
configuration. It will have the form:
http://<hostname>:<port>/<path>
Where:
• <hostname> should be replaced with your hostname. If you are
accessing the application using a browser on the host system
this can be replaced with localhost.
• <port> should be replaced with the port that the web server
listens on. The default port for web servers is 80. If your web
server is configured to listen on port 80 the port and
preceding colon can be left out.
• <path> is optional unless another WAR has already been
deployed for the same web server. In that situation <path>
would be replaced with the name of the directory that was
created when the web application WAR was deployed. If, for
example, you renamed the WAR spatialfusionviewer that
should be used as the path.
The following example is a URL that could be used if the web
server is listening on port 80 and a single WAR is deployed:
http://www.example.com/
The following example is a URL that specifies both the port
number (8080) and the path (spatialfusionviewer):
http://www.example.com:8080/spatialfusionviewer
If the filename of the WAR is changed to SFViewer before it is
deployed, and the web server is listening on port 8080, the URL
would be:
http://www.example.com:8080/SFViewer
The WAR can also be renamed to prevent a URL that changes
with each updated WAR. See “RENAME THE WAR” ON PAGE 54
information.
The screen that opens in your browser is described in “BASICS OF
57.
THE INTERFACE” ON PAGE
56
6
Basics of the Interface
In this chapter...
OPENING THE WEB APPLICATION .................................... 58
INTERFACE COMPONENTS .............................................. 64
Basics of the Interface: Opening the Web Application
Opening the Web Application
Opening the web application is different, depending on your user
role. For installations with public access, the log in screen
(shown below) may not appear. For other users, a password and
a username are required. The privileges and features available
may be different if you are using a public role compared to an
administrative role.
The configuration of users is affected by whether LDAP has been
enabled or not.
• If LDAP has not been enabled, the Viewer Manager allows
the system administrator to configure users and their roles.
See “SECURITY” ON PAGE 101 for more information.
• If LDAP has been enabled, LDAP users can be imported into
the web application. See “LDAP” ON PAGE 113 for more details.
To access the Viewer or Viewer Manager:
1. Enter the following in the address bar of a browser window:
http://localhost:8080/spatialfusionviewer/
Instead of localhost, the actual name of the host computer can
be used.
For users with public access, the web application opens directly
with a map view. An example of this view is shown below.
58
For users who require the use of a password, the Login page is
displayed.
59
The default Username and Password for the Viewer Manager is
"admin" and "password". These can easily be updated through the
User Profile page by anyone with system administrator
privileges.
The language can be selected in the right corner of the banner.
Selecting a language on this page sets the language option only for the current
session.
A map viewer sample is also available. The Username and
Password for the sample are "demonstration" and "password".
2. Type the Username and Password, and click Login.
If you forget your password, see “REGAIN ACCESS TO YOUR ACCOUNT”
PAGE 111 for instructions on how to change your password.
ON
When logging in for the first time using the admin
(administrator) account, the License page is displayed. The
Expiration Date field is displayed empty below it.
60
By entering the license string and clicking Save you are
indicating that you accept the terms of the license agreement.
3. If you agree with the license agreement, copy and paste your license
string into the License Number field and click Save.
After it is saved, the Expiration Date is be displayed below the License
Number.
61
The Viewer Manager or the Viewer is now accessible. An
example of the Viewer Manager interface is shown below.
More detail about the parts of the interface can be found in the
remainder of this document.
62
Logging Out
When you select the Logout option in the top menu bar of either
Viewer or Viewer Manager, you are logged out of the system.
1. Select Logout.
The login screen is displayed.
2. To log back into the system, retype your username and password
values and click Login.
63
Basics of the Interface: Interface Components
Interface Components
The Viewer Manager is only displayed for users with the necessary privileges.
Public users are taken directly to the Viewer.
SFE Viewer Manager
An example of the Viewer Manager interface is shown above.
Banner links
• Logout: This link logs you out of the application, ending your
current session.
• Viewer: This link opens the map view of the web application.
• Contact Us: This link opens the CARIS Web site, which allows
you to submit a question or request to CARIS Customer
Support.
• Help: This link opens the CARIS SPATIAL FUSION VIEWER REFERENCE
GUIDE if you are logged in as admin.
64
Menu tabs
When selected, the menu tabs take you to individual pages. Each
page contains the same links provided on the Home page.
Viewer Manager links
• Map Configuration: This menu/section provides links to the
Data Connections and Themes pages. These pages allow you
to define which maps can be displayed in the web application
and to create themes from the data in those maps. See “MAP
CONFIGURATION” ON PAGE 69 for more information.
• Security: This menu/section provides links to the Users and
Roles pages. These pages allow you to create user accounts
and roles, and assign roles to the users. See “SECURITY” ON
• General: This menu/section provides links to the Settings,
Support, Logs and License pages. These pages allow you to
define settings for the application, view application logs,
change your license string and request customer support. See
“GENERAL OPTIONS” ON PAGE 121 for more information.
Version of Web
Application
The version number of the application appears below the links in
the upper right corner of the banner:
The version number is useful information if you need to contact
CARIS regarding the software you are using.
SFE Viewer
The Viewer link in the banner at the top of the Viewer Manager
interface opens the web application as it is currently configured
65
For users with administrative rights, the Help link opens the CARIS SPATIAL
FUSION VIEWER REFERENCE GUIDE.PDF (this document).
For non-administrators, the CARIS SPATIAL FUSION VIEWER HELP GUIDE is
available in English, French and Spanish from the help menu link of the
interface.
Changing the Appearance of the Web
Application
Display settings for the interface can be customized using the
map-custom.css style sheet provided. This file controls each of
the elements of the interface, such as the font style used for each
heading type.
Making changes in this file can cause your application to stop
performing correctly. For this reason, the .css file should only be
edited by an administrator with an advanced understanding of
style sheet development.
The map-custom.css file can be found in the following directory:
66
…\Apache Software Foundation\Tomcat 8.0\webapps\
spatialfusionviewer\styles\mapviewer
A number of .css files are present in the install folders, but only
the map-custom.css file should be edited. This file is included
last in the set of style sheets, and it will override the settings
from all other .css files.
Note that a copy of this file is placed in Tomcat's Temp folder
when Tomcat is started and the spatialfusionviewer.war file deployed.
The file is then run from the Temp folder, not the Styles folder.
Be sure to make your edits in the file in the Styles folder, to
prevent having your changes overwritten when you restart the
Tomcat service.
The customization of the file is performed using a combination of
web development tools and integrated development
environments (IDEs). These tools allow you to identify and
inspect the elements of the interface from within a browser. An
example of a modified .css file (map-custom-example.css) is provided
in the Styles folder.
67
68
7
Map Configuration
In this chapter...
DATA CONNECTIONS ..................................................... 70
POINTS OF INTEREST .................................................... 76
USING PHOTO AND VIDEO WEB FEEDS FOR POIS .............. 80
USING A WFS TO DISPLAY POIS ................................... 85
THEMES ..................................................................... 86
Map Configuration: Data Connections
Data Connections
The Data Connections page in Spatial Fusion Manager allows
you to create and edit connections to registered map data
through a Web Map Service (WMS), Web Map Tile Service (WMTS),
Web Feature Service (WFS), or Web Coverage Service (WCS).
WCS services are only available for Bathy DataBASE data though a Bathy
DataBASE Server™ connection.
Add Data Connections
To create your own data connection:
1. Select Data Connections from the Map Configuration menu or from the
Map Configuration section of the Home page.
The Data Connections page is displayed.
Existing data connections are listed along with their status.
A data connection has a status of "Unavailable" when a connection cannot be
made to the server identified by the web service URL.
See “SECURE SOCKETS LAYER”
secured servers.
ON PAGE
169 for information on connecting to
2. Click Add.
70
3. Select a Type for the connection from the drop-down list: WMS, WMTS,
WFS, WCS or POI.
If POI is selected as the type, the fields on this page will change to allow POIspecific information to be entered. See “CREATING A POI CONNECTION” ON
PAGE 16 for more information on creating a POI data connection.
The Data Connection page is displayed.
If you are creating a WFS with Version 1.0, it will be necessary to set up a WFS
with a single Coordinate System as the WFS 1.0 specification does not permit
data reprojection.
4. Enter a Name for the data connection. This should be something that
clearly identifies the data in the map.
5. Enter the Version of the data type.
6. Enter the URL of the connection.
7. Click Save.
The data connection is created. The data connection details and
layers available in the new map are displayed.
71
8. Click Back to return to the Data Connections page.
Edit Data Connections
You can edit existing data connections, if necessary.
To edit a data connection:
1. Select a connection name from the list.
The Data Connection page is displayed.
72
2. [Optional] Enter a new name in the Name field.
3. [Optional] Update the Version for the connection, if a different version
is available.
4. Click Save.
The data connection is updated.
5. Click Back to return to the Data Connection page.
If the Web service for a data connection has been modified after
the connection has been created, the following dialog box is
displayed the next time you access the connection.
73
This dialog box allows you to automatically update the
connection with changes to the data source.
6. Click Apply Changes to update the data connection and close the
dialog box.
Delete Data Connections
If a data connection is no longer needed, it can be deleted from
the Data Connections list.
To delete a data connection:
74
1. Select the check box of each data connection you wish to remove. (To
delete all connections, select the check box at the top of the list.)
2. Click Delete.
A message is displayed warning that you are about to make a
permanent deletion.
3. Click Yes to continue.
The selected data connections are deleted from the list.
75
Map Configuration: Points of Interest
Points of Interest
A Point of Interest (POI) connection is a uniform resource locator
(URL) connection to a file that contains spatial data in either
one of the following formats:
• Keyhole Markup Language (KML), or
• GeoRSS_SIMPLE.
Each POI connection added to a theme becomes a map layer
with an image representing spatial data. The on-screen POIs are
determined by the data in the file as described below.
Point data is displayed as a point with the image displaying at
that location. When a line or a polygon geometry is converted to
a POI, the application determines the centroid of the feature and
the POI image is shown at the centre point of the line or the
polygon.
Creating a POI
Connection
To create a POI connection in the Data Connection page, you
need to specify the URL to the file, the format of the file, the
Spatial Referencing System (SRS) the file uses, and an image for
the display.
POIs are supported only in EPSG:4326. This means all four POI formats must
support EPSG:4326 for the POIs to draw in the correct location on the map.
To set up a POI Connection:
1. Select POI as the connection type on the Data Connections page.
2. Click Okay.
76
3. Enter a Name for the connection.
4. Enter the URL for the POI source.
5. Select the format of the POI data using the drop-down list.
6. Click the Icon link to select an icon to represent this POI connection.
The screen shot below shows the icons that are available.
77
You can add your own icons to this collection. See “ADDING POI ICONS”
PAGE 19 for more details.
ON
7. Select an icon and click Okay to return to the Data Connection page.
8. Click Save.
The POI data connection is created. The POI layer associated to
the POI connection needs to be added to the themes in which the
POIs are displayed. POIs are always displayed on top of the
map. See “THEMES” ON PAGE 28 for more information.
78
Adding POI Icons
An administrator can add POI icons by placing the graphic files
in this folder:
<drive>:\Program Files\Apache Software Foundation\Tomcat
8.0\webapps\spatialfusionviewer\images\configmanager\icons\P
OI
where <drive> represents the drive on which the web application
was installed.
Where and how to get POI connection URLs
POI data can be displayed in the web application in several
ways, depending on the available connections and data format.
Export KML from
Google Earth
In Google Earth, you can save My Places to a KML file by rightclicking My Places and selecting "save places as" in the pop-up
menu. Select KML as the "save as type".
Deploy a KML file on a
web server
Next you need to place the KML file in a folder on a web server
and get the URL of the file. Ideally a static web server like
Apache should serve these files. Apache can serve static
documents faster than Apache Tomcat; however, if this is not an
option, you should create a sub-directory in the webapps
directory of Tomcat to serve these files. The URL should be:
http://your.server.name:port/kml/[static.file.name]
You can use this URL to create the POI connection in the web
application.
GeoRSS_SIMPLE
You can use GeoRSS feeds (providing they follow the simple
format) and display them on the map as Points of Interest.
Some common feeds can be found at
http://www.fmepedia.com/index.php/GeoRSS_Feed
When creating a POI connection, be sure to use the URL of the
GeoRSS feed in combination with the GeoRSS_SIMPLE format.
For more information on GeoRSS Simple, please refer to the
following source:
http://www.georss.org/simple.html
79
Using Photo and Video web feeds for POIs
The web application supports using photo and video web feeds
for Points of Interest (POIs). The association between the web
application and the web feeds is made with a POI Data
Connection. The web feed formats supported for the POI data
connection include:
• YouTube
• Picasa
• Flickr
Preconditions
There are some preconditions that must be met in order to link
photos or videos on external web sites to the web application
maps.
• The web application supports only Picasa, Flickr and
YouTube.
• The web application only links to active accounts.
• Accounts must contain at least one public photo or video.
• The photos or videos must be georeferenced.
• The URL of the source account must be available.
80
Georeferencing
Georeferencing, in this context, is that act of assigning a location
to a photograph or video. It is performed via the user interface of
the photo or video service:
• Picasa: https://support.google.com/picasa/answer/66969?hl=en&rd=1
• Flickr: http://www.flickr.com/help/map
• YouTube: http://www.youtube.com
Georeferencing is also known as geotagging and geolocating.
At time of writing, the following steps can be used to
georeference a video on YouTube:
1. Log into your YouTube Account
2. Click Account name in the upper right-hand corner and click Video
Manager.
A list of all your videos will now be visible.
3. Click the Edit button of the video you wish to georeference.
4. Click the Advanced Settings tab.
5. Click the Video Location text field.
A map window will now be visible.
6. Drag the marker to the location you wish to set for your video.
The result will be a georeferenced video.
Photo web feed
Grouping photos in albums provides a convenient way of
accessing all the photos as a POI layer.
Determining the web feed URL can be a very simple operation. If
you navigate to the image or album you wish to use as a POI,
there is often an RSS feed link with an appropriate icon, such as
this one.
The link may also be shown with a hyperlink.
To determine the location, right-click and select the Copy Link
Location option.
81
It may be convenient to paste the location into a text editor until
it is needed. Later on, the link can be pasted into the URL text
box when the Data Connection is set up in the web application.
YouTube
At time of writing, the video web feed for YouTube videos must
be determined using the method described below.
Login to YouTube, and then navigate to the YouTube API Demo
interface:
http://gdata.youtube.com/demo/index.html
On the API page, enter the Author name and possibly other options
such as Output Format (Atom). This normally gives the API enough
information to determine the Resulting URL feed, which is listed in
its own text box on the web form.
By copying and pasting the URL feed into a browser, your RSS
feed reader is updated with all the new feeds from the author
you selected. (Your RSS feed reader may be set up in another
application, such as an email reader.) The appropriate URL can
usually be clicked to open the video in a browser. The link in the
feed reader can be copied and later pasted into the web
application to configure a POI, as described below.
82
Configure a Photo or
Video POI
To Configure the web application for POIs with photo or video
web feeds:
1. Navigate to the Data Connections page and click the Add link.
2. Select the POI Data Connection.
3. Enter a suitable name for the POI data connection.
This name will become the name of a new POI Layer that can be
added to a Theme.
4. Copy the photo or video web feed to the URL text box.
5. Select the type of POI web feed you are using in the drop-down list of
formats.
The type of feed must match the format type you select from the drop-down list.
The data connection will fail if the format does not match.
Photo or video web feeds incorporate their own thumbnail image
as a POI icon, and as a result, the icon option is not available.
6. Click Save.
If the URL is working, the POI Data connection will be saved,
and a message will indicate that status.
7. Navigate to the list of Themes.
If you are creating a new Theme and Layers for the POIs, see “THEMES”
ON
83
8. Select a Layer on which you would like to display the web feed POIs.
9. On the Theme page, configure the POI data sources that you wish to
display.
You can move all the items from one selection box to the
other by clicking the move buttons.
Each item can also be dragged from its current location to
a new location. The sequence of items in either box can be
changed by dragging items up or down within the same selection
box.
10.Move the layers to the desired locations by using the move buttons, or
dragging items.
11. Click save to save the changes to the POI Configuration.
12.If necessary, add the Theme to the desired Role or Roles, and save the
changes.
Navigate to the map with an appropriate login to view the POI
layer. Click on points in the map to view the video or photo.
84
Using a WFS to display POIs
A WFS service from a Spatial Fusion Server outputs the feature
data in KML format. You can create different POI connections to
the WFS service in the web application to get the feature data
displayed as POIs. The URL of a POI connection is the URL of a
GetFeature request to the WFS service with the outputFormat
parameter set to the values listed in the table below.
WFS Version
Format
Value of the OutputFormat Parameter
1.0.0
KML
kml
1.1.0
KML
text/xml; subtype=kml/2.2
When creating a WFS URL, you have the ability to retrieve
subsets to get the exact data you need by using parameters such
as the box or filter. The filter takes in an XML file that follows
the Open Geospatial Consortium, Inc. (OGC) Filter Encoding
Specification.
An example URL is shown in the following table:
http://localhost:8080/sfs/
ogcAction?servicename=fredericton_wfs&service=WFS&request=GetFeature&ver
sion=1.1.0&typename=building,roads&srsName=EPSG:4326&outputFormat=text/
xml;%20subtype=kml/2.2
85
Map Configuration: Themes
Themes
The Themes page is used to create themes using the layers of
data from data connections. Themes are accessible to the end
user in the Map List in the web application.
Themes are generally used to group similar or related data
together. For example, you may wish to create a theme for data
relating to a particular project or geographic area.
There are no limits to the number of WMTS or WMS services
that can be configured. However, only one WCS and only one
WFS will be functional. More than one data source can be
configured to display in one theme.
Google Maps API
The Google Maps option configures the theme to use Google
Maps data as the base layer. This option is only enabled if you
have a Google Maps API key and the key is entered in the
Settings page.
Support for Google Maps was lost in the application when version 3.20 of the
Google Maps API was phased out. Support for Google Maps has been
restored. However, it is possible that support for Google Maps in the application
could be lost again, as Google makes changes to their product. If this happens,
we cannot guarantee that we will be able to recover support.
You will notice that, when panning and zooming, the movement of the base map
will not be synchronized with any data layers that are drawn on top.
Setting up the Google Maps API requires some preparation
before configuring the Theme that uses it.
When entering a new Theme, a link is provided to the Settings
page, where the API key is entered.
86
See “SETTINGS” ON PAGE 124 for more information.
When you return to the Theme page, the field will be enabled
and the link will have been removed.
Add Themes
To create a theme:
1. Select Themes from the Map Configuration menu or from the Map
Configuration section of the Home page.
The Themes page is displayed.
87
All existing themes are listed.
2. Click Add.
The Theme page is displayed.
88
3. Enter a Name for the theme.1
89
The Coordinate System for the Theme shows the location of the
cursor on the map. This can be a different coordinate system
from the data source, if desired. The web application will
recalculate the coordinates.
4. Select a Coordinate System from the drop-down list.
The EPSG:900913 code has been removed. EPSG:3857 is the code adopted in
the EPSG database for the CRS used by Google Maps and OpenStreetMap.
Only one Coordinate System can be used in a Theme and all its layers,
including the base layer. Use of different coordinate systems within a theme can
cause display problems.
If you wish to use a third-party base map, all of your layers must be in the same
coordinate system in Spatial Fusion Viewer.
5. Set the total number of zoom levels available for the map (the number
of times the map can be zoomed in or out) by entering a value in the
Number of Zoom Levels field.
The minimum number of zoom levels in the web application is 5,
and the maximum number 21. However, some external maps
override any setting made on the Theme page.
• OpenStreetMap has 19 zoom levels, and this setting will
override any zoom level setting.
• Google Satellite and Hybrid gives a "We are sorry" tile past
zoom level 20.
The Google Maps option will be disabled unless a Google API key
has been entered on the Settings page. See “GOOGLE MAPS API” ON
PAGE 86 or “SETTINGS” ON PAGE 124 for more information.
The Default World Map option links to the world map provided
on the CARIS Web site.
6. Select a Base Layer to display in the background.
To have the web application work without Internet access, all Themes must use
the None base map option, as most base maps require Internet access. Other
layers will need data from a WMS within a closed network or system.
1. Fields with an asterisk are required.
90
7. [Optional] If you chose Google Maps, select the layer type you want to
display from the drop-down list.
Data from multiple data connections can be included in single
theme. However, layers for each connection should be added
consecutively to optimize draw speed. If you have layer groups
created for a selected data connection, avoid adding both the
individual layer and a group containing that same layer. Having
both selected will call to the same data twice, slowing down your
draw speed unnecessarily. See “WEB SERVICES OPTIMIZATION” ON
PAGE 157 for more information about optimizing your data
configurations.
8. Configure the data layers that you want available in the theme. In the
Map Layers section, select a data connection and move layers from
Available Map Layers to Selected Map Layers to make them visible in the
theme.
Each item can be dragged from its current location to a
new location. The sequence of items can be changed by dragging
items up or down within the same selection box.
Any available POI Layers will be visible in the selection
9. If desired, move Available Points of Interest (POI) Layers to the
Selected POI Layers box by clicking the move buttons, or dragging
items.
91
Selection data can be included in the theme if it is available.
10.Move the Selection Data layers to the desired locations by clicking the
move buttons, or dragging items.
If there are WFS or WCS data sources containing downloadable
data that you want included in the theme:
92
11. Click the Data Connection containing the desired data.
You can add a legend to the map. A legend is an image that you
create in a graphics package and save on the computer that
hosts the web application. The image is selected during the
configuration of the theme and is displayed in the map when the
theme has been selected.
12.Click the Map Legend button to open the file upload dialog.
93
You can browse the file system of the computer that hosts the
web application to locate the legend file desired.
13.Select the appropriate image and click Open to upload the file to the
web application.
The selected image will be displayed in the Theme
configuration page. Note that the image can be removed so
that a different image can be selected. The theme
configuration must be saved in order for the selected image to
be used as the legend in the map view.
94
14.Click Save.
The theme is created.
If you are not using EPSG:4326, EPSG:900913 or ESPG:3857 then you must
specify the Maximum Bounding Box for a Theme. Failing to do so will result in
drawing problems in the Viewer. See “BOUNDING BOXES” ON PAGE 36 for
instructions on how to make this setting.
95
Once a theme has been saved, links are added to the page for
Localize and Set Bounding Boxes. These links allow you to:
• Provide the appropriate theme name for each of the
application’s language options.
• Define the extents of the theme. If nothing is defined, it will
default to the extents of the selected Base layer.
Localization
15.[Optional] Select Localize if the theme is to be used in various
languages.
The Localizations dialog box is displayed.
16.Enter the name you would like displayed for each language.
17.Click Save.
18.Click the X (Close button) to return to the Theme page.
The localization has been defined.
Bounding Boxes
Unless the bounding box is set, users will need to navigate to the
map location each time a map is opened.
The default World Map, Google Maps and OpenStreetMap define their own
maximum bounding box settings. Any maximum bounding box settings in the
web application for these base maps will be ignored.
To set the Bounding Box limits:
19.Select the Set Bounding Boxes link.
The Bounding Boxes dialog box is displayed.
96
20.To define the default extents for this theme, enter coordinate values in
the Min and Max X and Y fields in the Default Bounding Box section.
21.To define the maximum possible extents for this theme, enter
coordinate values in the Min and Max X and Y fields in the Maximum
Bounding Box section. These extents will be used to configure data for
the Overview window.
22.Click Save.
A message is displayed stating that the extents were saved.
97
23.Click Back to return to the Theme page.
Edit Themes
You can edit the settings of an existing theme, if necessary.
To edit a theme:
1. Select a theme Name from the list.
The Theme page is displayed.
2. Make any necessary changes.
3. Click Save.
The theme is updated.
4. Click Back to return to the Themes page.
98
Delete Themes
If a theme is no longer needed, it can be deleted from the Themes
list.
To delete a theme:
1. Select the check box of each theme you wish to remove. To delete all
themes, select the check box at the top of the list.
2. Click Delete.
permanent deletion.
3. Click Yes to continue.
The selected themes are deleted from the list.
99
100
8
Security
In this chapter...
USERS ..................................................................... 102
ROLES ..................................................................... 106
REGAIN ACCESS TO YOUR ACCOUNT ..............................111
LDAP ..................................................................... 113
Security: Users
Users
The configuration of users is affected by whether LDAP has been
enabled or not.
• If LDAP has been enabled, see “LDAP” ON PAGE 113 for more
details on the configuration of users.
• If LDAP has not been enabled, the Viewer Manager allows
the system administrator to configure users and their roles.
The procedures are described in this section of the manual.
The remainder of this Users section describe the configuration of
users when LDAP has not been enabled.
Through the Security menu options, you can create and manage
user accounts.
The Users options allow you to add, edit, and delete user
accounts.
See:
• “ADD/EDIT USERS” ON PAGE 102
• “DELETE USERS” ON PAGE 105
Add/Edit Users
To add or edit users:
1. Select Users from the Security menu or from the Security section of the
Home page.
The Users page is displayed.
2. To add a new user, select Add.
OR
To edit an existing user, select a Username from the list.
The User Profile page is displayed.
102
Security: Users
If you are creating a new user, the fields in the Required section will be blank.
3. For each field in the Required section, type a value1.
4. [Optional] Type or select any additional useful or available information
in the fields in the Optional section.
A role provides users with access to certain tools and themes,
based on the privileges associated with the role. See “ROLES” ON
1. A value is required for any field, list or option with an asterisk.
103
Security: Users
In the Roles section, you will need to add or remove roles to create
the desired user access.
box.
5. Move the roles to the desired locations by using the move buttons, or
dragging items.
6. To save the user account and information, click Save.
The new user, or updates to an existing user, are saved.
7. To return to the Users page, click Back.
104
Security: Users
You can track and manage the activity of users using the Apache
Tomcat Manager. See “MONITORING USER CONNECTIONS WITH APACHE
SERVER” ON PAGE 155 for more information.
Delete Users
You can also delete users if necessary. To delete one or more
users from the list:
1. Select the check box of each user you wish to remove and select
Delete. To delete all users, select the check box at the top of the list
and select Delete.
permanent deletion.
2. Click OK to continue.
No check box is available for the administrator user; this user cannot be deleted.
The selected user accounts are deleted from the Users page.
105
Security: Roles
Roles
Roles are collections of permissions that can be assigned to
users. The web application provides the administrator role and
the publicuser role.
The configuration of roles is not affected by whether LDAP has
been enabled or not. Whether new users are acquired through
LDAP or the web application, the administrator must assign
privileges to users before users can access Themes and map
data.
For more information about LDAP, see “LDAP” ON PAGE 113 .
The administrator role has access to all tools and options in the
Viewer Manager, as well as viewing data in the Viewer. This
includes:
• adding, editing and deleting user accounts,
• assigning privileges to users,
• creating data connections and themes,
• defining the settings for the application,
• accessing the application logs, and
• generating support requests.
The publicuser role is limited to viewing data in the Viewer. This
includes:
• Turning on and off the themes that they have permission to
view, and
• Adjusting the view with the zoom and pan tools.
Users with administrator privileges can create additional roles
as needed and edit existing roles.
The themes a user can view in the Viewer is controlled by the
themes associated with the role assigned to the user. Although a
role can be saved without a theme assigned to it, a theme is
necessary before the role can be used.
For further information see:
• “ADD ROLES” ON PAGE 107
• “EDIT ROLES” ON PAGE 109
• “DELETE ROLES” ON PAGE 110
106
Security: Roles
Add Roles
To add a role:
1. Select Roles from the Security menu or from the Security section of the
Home page.
The Roles page is displayed.
2. Click Add.
The Role page is displayed.
3. Enter a name for the role in the Name field.
107
Security: Roles
You now must add to the list of Selected Themes each theme you
want to assign to the role.
box.
4. Move the themes to the desired list by using the move buttons, or
dragging items.
5. Click Save.
The role is saved and can now be assigned to users.
6. To return to the Roles page, select Back.
The role you created is added to the list.
One role in the list can be designated for public access. Users
with this role are not required to login to access the Viewer. You
can designate a different role as public access by clicking the
radio button for the role. If you do not wish to have public access
designated to any of the roles, click the Disable Public Access
option. None of the radio buttons will be selected.
108
Security: Roles
Edit Roles
Existing roles can be edited if permissions require adjustment
after the role has been created. To edit a role:
1. Select the role Name in the list.
The selected role profile is displayed.
2. [Optional] Change the name of the role.
You can move the themes from one selection box to the
box.
3. [Optional] Move the themes to the desired list by using the move
buttons, or dragging items.
4. Click Save.
The role is updated, and a confirmation message is displayed.
109
Security: Roles
If you make changes to a role that is currently assigned to a
user, those changes will automatically be updated in the user’s
profile when you save the role. If the user is logged in to the
application at the time the changes are made, they will need to
log off and back in to see the difference.
Delete Roles
You can also delete roles if they are no longer necessary. To
delete one or more roles from the list:
1. Select the check box of each role you wish to remove and select
Delete. To delete all roles, select the check box at the top of the list and
select Delete.
permanent deletion.
2. Click OK to continue.
No check box is available for the administrator role; this role cannot be deleted.
110
Security: Regain Access to your Account
Regain Access to your Account
If you forget the password assigned to your account, you can
often gain access to your account and update it with a different
password.
The Forgot your password? link will not appear if LDAP authentication has
been enabled. In that situation you will need to use the password for admin, or
contact the system administrator for assistance.
1. From the login page, select Forgot your password?.
The Forgot your password? message is displayed.
2. Type your Email address in the text field.
3. Click Submit.
The system sends an email with a temporary “confirm change”
password to your account. It may take a few moments for your
email server to finish sending the update information to your
email address.
4. [Optional] To return to the main login page without submitting your
email address, click Cancel.
An email with the subject line, "Reset your Password", is sent to
your email account.
5. From your email account, select the Reset your Password email.
6. Click the link within the email or copy and paste the link into the
Address (URL) field in your browser and press <Enter> to confirm you
want to change the password.
Another email with the subject line "Your New Password" is sent
to your email account. This email contains a system-generated
111
Security: Regain Access to your Account
password. This password is now recorded in your user profile as
the accepted password. If you wish to change it, you can update
it in the Users profile page.
Public users should be informed of this option any time their password is
changed by the application.
7. From the login page, type the Username and the new Password.
8. Click Login.
The Viewer Manager is displayed.
9. From the Security section, select Users.
The Users page is displayed.
10.From the User list, select your user profile.
The User Profile page for your account is displayed.
11. Type and confirm the new password for your account.
12.To confirm the change, select Save.
The User Profile page, with an “updated successfully” message,
is displayed.
Your user account is updated with the new password.
112
Security: LDAP
LDAP
The web application supports access to a Lightweight Directory
Access Protocol (LDAP).
The web application can connect to an LDAP server to
authenticate users. When a successful connection is made to an
LDAP server, the user authentication is delegated to the server.
With LDAP authentication, administrators of the web
application are no longer able to create new users and passwords
from the web application, and users are no longer able to reset
their own passwords.
Only users with email addresses entered in the LDAP server will be available for
import into the web application.
LDAPS
See “SECURE SOCKETS LAYER” ON PAGE 144 for information on
connecting to secured servers.
Restricted Role
Users imported from an LDAP server must be assigned a role
from those available on the Roles page. If the user attempts to
log in to the configuration pages before being assigned a role,
they will be presented with a message directing them to contact
their administrator who should assign them a role. Users must
have an administrator role in order to access the configuration
pages. Users may be assigned roles which allow them service
access or service transaction permissions on the web services.
Once the users have been imported from the LDAP server to the
web application, the administrator can then assign roles to the
imported users as appropriate.
113
Security: LDAP
User Management with
LDAP
Since the username and Email fields are taken from the LDAP
server, these fields are now read-only in the web application.
The Password and Confirm Password fields are removed from the web
application, since the passwords are stored on the LDAP server.
Password changes made on the LDAP server do not require
importing users into the web application, and a password change
made in the LDAP server is effective immediately in the web
application.
If a user’s email or username changes on the LDAP server, the
user must be removed from the web application and then
imported again in the application using the Import LDAP Users
link. Only users who have an email address entered in the LDAP
server are available for import into the web application.
Users created in the web application before LDAP
authentication is enabled will be retained, but after LDAP is
enabled new users must be imported from LDAP. To prevent
duplicates, any request to import users through LDAP will only
list user names that do not exist in the web application.
Admin Account
When the web application is installed, one user is created, admin.
This user is special in that, even if LDAP authentication is
enabled, this user's information and password are still stored in
the web application database, and can still be edited on the
profile page. This ensures that the admin account is always
accessible even if the LDAP server is not running.
Turn LDAP ON/OFF
The web application is intended to be used either with or
without LDAP enabled. Switching back and forth between LDAP
and non-LDAP modes causes difficulty in user management and
is not recommended. Organizations with a large number of users
in particular should avoid switching back and forth between
LDAP and non-LDAP authentication.
If LDAP is turned off, any existing users of the web application
are no longer authenticated through the LDAP server. However,
all of the existing user accounts still exist in the application.
Users are assigned randomly-generated passwords. As a result,
users must use the now-enabled Forgot Password link to reset
their own passwords and regain access to the application.
114
Security: LDAP
Enable LDAP Authentication
To configure and activate LDAP authentication:
1. If necessary, create a new Organizational Unit (OU) in your LDAP server,
and assign it an appropriate name.
2. Inside the OU for Spatial Fusion Enterprise™ (SFE) users, add all users
that should have access to the web application, to record the selection
for later export.
3. Log in to the web application and navigate to the Settings page.
4. Type ldap in the filter box. The filter selects the available settings for
LDAP.
5. Fill in the required settings for your specific LDAP server.
Setting
Description
Example
ldap.base.dn
LDAP root node from which to search for users. If you
have created a specific Organization Unit (“OU”) for the
web application use that value.
ou=People,dc=example,
dc=com
ldap.bind.dn
The user name of an account that has privileges to
view all users. This setting can be left blank if your
LDAP server has enabled anonymous read access.
cn=admin,dc=example,
dc=com
ldap.bind. password
The password of the account that has privileges to
view all users. This setting can be left blank if your
LDAP server has enabled anonymous read access.
The attribute in your LDAP server that stores the user's
email address. This value is imported into the web
application.
The default value is "mail"
ldap.email. attribute
ldap.external.
authentication. enabled
A value of "true" turns LDAP on, while "false" turns it
off. Trying to set this to any other value results in an
error.
The default value is "false"
115
Security: LDAP
Setting
ldap.query
Description
Example
LDAP query run under the ldap.base.dn that identifies
users.
ldap.query=(objectcla
ss=person)
The default value is
(objectclass=person)
ldap.search. attribute
Name of the records in LDAP nodes that become the
usernames in the web application.
ldap.url
The URL of the LDAP server.
ldap.search.attribute
=uid
6. After the settings have been updated, stop and restart Tomcat to
implement the changes.
Use LDAP Authentication
After LDAP authentication has been enabled, the Add link on
the web application List Users page is replaced with an Import
LDAP Users link.
Once user data has been imported from the LDAP server to the
web application, users must be assigned roles from those
available on the Roles page in order to acquire service access or
service transaction permissions for web services that require
authentication. Only users with the administrator role will be
able to access the configuration pages.
To assign LDAP users a user name in the web application:
1. Navigate to the Users page.
116
Security: LDAP
2. Delete any Usernames that will be imported from the LDAP server (for
example, with an updated email address).
An LDAP user with the same Username as an existing user in the web
application cannot be imported from the LDAP server.
3. Click Import LDAP Users.
A page with a list of users is presented. These users:
• belong to the LDAP base Distinguishing Name (DN),
• have an email address, and
• do not have the same user name as any existing user in the
web application.
4. Select which users to import by clicking on the check box beside the
desired name (or names).
The search box can be used to filter for names.
5. Click Import LDAP Users to import the selected users.
117
Security: LDAP
After being imported, the users appear in the Users page of the
web application.
To give users access to the application:
6. Click the user's name on the Users page.
The User Profile page is displayed.
118
Security: LDAP
When users are first imported from LDAP they are assigned a
special role named Restricted. This role has no permissions and
cannot be configured. Users must be assigned roles available on
the Roles page in order to gain service access or service
transaction permissions for web services that require
authentication. Users must be assigned the administrator role
in order to access the configuration pages.
7. Add a new role to the user's existing roles (e.g, the administrator role, if
that is appropriate).
Removing the restricted role is optional.
119
Security: LDAP
Many user details (such as Username and Email) can not be edited
in the web application. It is necessary to use the LDAP server to
make changes to these details.
Disable LDAP Authentication
After LDAP authentication has been enabled, it can be disabled
if desired.
Disabling LDAP authentication after users have been set up causes difficulties
in user management and is not recommended. See “TURN LDAP ON/OFF” ON
To disable LDAP authentication:
1. Log in to the web application and navigate to the Settings page.
2. [Optional] Type ldap in the filter box. The filter selects the available
settings for LDAP.
3. Change the ldap.external.authentication.enabled field to "false".
LDAP Authentication is disabled.
120
9
General Options
In this chapter...
DEFAULT LANGUAGE KEY ............................................ 122
SETTINGS ................................................................. 124
SUPPORT.................................................................. 126
LOGS ....................................................................... 127
LICENSE ................................................................... 131
General Options: Default Language Key
Default Language Key
The web application can be configured to use the locale provided
by the locale settings of the browser being used. If there is no
match, then the application has a default locale setting in the
Settings page that it would then use.
In effect, this permits the administrator to give the web
application a default language other than English.
The web application allows for the request_locale to be read from
the URL to render the page in the appropriate language. If the
given request_locale does not match one of the web application's
supported languages, then it will default to English.
• Setting the language preference in the User Profile will take
precedence over the default locale setting when a user is
logged in.
• Setting the language default locale will set only the language
preference on the login/public pages of the Viewer and Server.
• The user will still be able to select a different language on the
login or map viewer page (for public use) that will be
maintained throughout the session.
If you do not have a public role and the administrator would like
users to be able to choose their own default language, users can
make that selection on the User Profile page.
English Map Examples
(default)
http://your.domain.com/spatialfusionviewer/mapViewer/map.action?request_locale=en
http://your.domain.com/spatialfusionviewer/mapViewer/
map.action?request_locale=en_US
map.action?request_locale=ja_JP
In the last example, the browser will use English, as Japanese is
not a supported language.
French Map Examples
http://your.domain.com/spatialfusionviewer/mapViewer/map.action?request_locale=fr
map.action?request_locale=fr_FR
122
General Options: Default Language Key
Spanish Map Examples
http://your.domain.com/spatialfusionviewer/mapViewer/map.action?request_locale=es
map.action?request_locale=es_MX
map.action?request_locale=es_ES_EURO
123
General Options: Settings
Settings
The Settings page is used to set environment variables for the
Viewer application. These settings can only be changed by a user
with the administrator role.
To change a variable:
1. From the General section, select Settings.
The Settings page is displayed.
2. To filter the settings listed by Name, type one or more characters in the
Filter by Name field.
3. To clear the filter and show all available settings, click Show All.
124
General Options: Settings
All available settings are displayed.
4. [Optional] To sort the settings, in the settings table, click a column
heading.
By default, entries listed in the Settings table are sorted in
ascending (lowest-to-highest: 0-9, A-Z and a-z) order. When a
column heading is selected, an up arrow is displayed in the
heading cell. To have the values sorted in descending (highestto-lowest) order, click the heading again.
5. To change a setting value, select the table cell of the value to change.
An update dialog box is displayed.
6. Type the new value and click Save.
7. [Optional] To close the dialog box without changing the previous value,
click Cancel.
8. To change a setting back to its default value, select the Reset button
(
) for the desired setting.
The Settings Page is used to change the logging level. See “LOGGING LEVEL” ON
PAGE 129 for an explanation of the logging levels.
125
General Options: Support
Support
The Support page allows you to submit support requests and
Viewer logs to the email address designated for support. By
default, this address is [email protected], however, it can be
changed in the Settings page if desired.
To use this page:
1. From the General section, select Support.
The Support page is displayed.
2. Type values for all required1 fields (Contact Name, Phone Number
and Email).
3. [Optional] Type the Service Request Number assigned to your
request (this number is provided, as needed, by CARIS Customer
Support after you have contacted CARIS for support).
Note: If the support.email value in the Settings page is not a CARIS email
address (e.g., [email protected]), the Service Request Number field is not
displayed.
4. [Optional] Type any additional information or comments in the Problem
Summary text box.
5. To submit the logs from your account to CARIS, select Send Logs.
The logs from your account (application and servlet container
logs) have been sent to the account specified for handling email
support service.
1. For any field, list or option with an asterisk, a value is required.
126
General Options: Logs
Logs
The Logs page allows you to view the logs for the web
application. Log entries are generated whenever there is system
activity or an error occurs in the application. Logs are separated
into two categories, Application Logs and Servlet Container
Logs.
Application Logs
These logs record activity and errors that occurred in the
application.
The main log file for the web application is the spatial fusion
file. Errors will be logged when a warning, error or
fatal event occurs. The spatial fusion viewer.log file records
events originating from CARIS code.
viewer.log
Servlet Container Logs
• The following log files record information, activities and
errors that occurred in the Apache Tomcat service:
• localhost.[date].log,
• host-manager.[date].log,
• catalina.[date].log, and
• those containing "stdout" in the file name.
For more information see:
http://tomcat.apache.org/tomcat-8.0-doc/logging.html
Viewing Log Files
To view a log entry:
1. From the General section, select Logs.
The Logs page for your account is displayed.
127
2. From one of the log tables, select the name of the log file to view.
Example: Servlet container log file excerpt.
3. To go back to the Logs page, select Back.
Logs can be deleted if they’re not required.
The currently active log, spatialfusionviewer.log, cannot be selected or deleted
from the log table.
To delete a log:
1. Select one or more application logs by checking the check boxes.
Select the check box at the top of the list to select all logs in the table.
2. Click Delete.
The selected application logs are deleted.
128
Logging Level
The number and types of logs can be set to five different levels.
The highest level, "FATAL", only reports fatal errors in the log
files, while the lowest level, "DEBUG" will report any and all
problems.
Amount of
Information
Logging Level
Description
Least
FATAL
Only reports fatal events.
ERROR
Reports fatal, and error events.
WARN
Reports fatal, error, and warning events.
INFO
Reports fatal, error, warning and info events.
DEBUG
Reports fatal, error, warning, info, and debug events.
Most
The default logging level is FATAL. Increasing the level of
logging is very useful if your installation of the web application
has any problems. By setting the logging level to record as much
information as possible, Customer Support at CARIS may be
able to use the log files to diagnose a problem quickly.
To set the logging level:
1. Navigate to the Settings Page.
The General > Settings menu sequence can be used.
2. [Optional] To display the logging level field quickly, enter "log" in the
Filter by Name field.
3. Click on the value field.
129
4. Enter the desired logging levels from the list of five logging levels
above.
5. Click Save.
The logging level is set to the level you have entered. See
“SETTINGS” ON PAGE 124 for more information on changing Settings.
130
General Options: License
License
The License page is used to update the web application license.
In the case where the current license must be renewed, an email
notification is sent at least two weeks before the current license
for the service is set to expire.
1. From the General section, select License.
The License page is displayed.
2. To update the previous the web application license (e.g., the current
license is about to expire), paste the new license string, provided by
CARIS, in the License Number field.
3. To save the update, select Save.
A confirmation message indicates that the license for the service
is updated.
131
General Options: License
132
A
Advanced Configuration Settings
In this chapter...
CONFIGURATION DATABASE ......................................... 134
APACHE WEB SERVER ................................................ 135
APACHE TOMCAT........................................................ 137
WEB ROBOTS ........................................................... 142
SECURE SOCKETS LAYER ............................................ 143
Advanced Configuration Settings: Configuration Database
Configuration Database
The web application stores its configuration in an HSQLDB
database.
The location of the database is controlled by two Java options.
The default location is the directory identified by
java.io.tmpdir. However, if com.caris.sfv.dir is set the
database location will be the directory identified by this option.
The com.caris.sfv.dir option overrides java.io.tmpdir in the
case of SFV configuration data.
The database communication port for Spatial Fusion Viewer
occurs on port 9002 by default. If more than one instance of the
web application is set up on a system they should be configured
to use different databases using the
com.caris.sfv.dircom.caris.sfd.dir Java option and different
ports for database communication. See “CHANGE THE DATABASE PORT”
ON PAGE 141 for more information.
134
Advanced Configuration Settings: Apache Web Server
Apache Web Server
Apache HTTP Server can be used as a reverse proxy (or
gateway) server for back-end Tomcat server(s) running Spatial
Fusion Viewer and other web applications.
This section shows how to configure Apache Web Server for
back-end Tomcat server(s) running web applications.
HTTP Compression
Compression provides a way of reducing the size of HTTP
messages returned by Apache Web Server. CARIS has found
compression to be very successful in reducing the response time
for client applications, and thus substantially improving the
user experience. CARIS recommends this technique for
production environments.
This section refers to Apache Web Server 2.4. Refer to the
documentation for the version of Apache Web Server that you
are running.
This example requires the following modules:
• mod_deflate
• mod_filter
• mod_headers
The documentation for these modules can be found on these web
pages:
• http://httpd.apache.org/docs/2.4/mod/mod_deflate.html
• http://httpd.apache.org/docs/2.4/mod/mod_filter.html
• http://httpd.apache.org/docs/2.4/mod/mod_headers.html
Compression can be applied selectively depending on the content
type of the response. You can decide which types to compress
using the AddOutputFilterByType parameter. Variations in
performance as a result of implementing compression for a
particular type depend on:
• The type of data being transferred
• The volume of data being transferred
Determining the optimum configuration for the use of
compression requires analysis. The following MIMEs usually
result in the greatest benefits:
• application/javascript
• image/gif
• image/png
• image/jpeg
• text/css
135
Advanced Configuration Settings: Apache Web Server
• text/html
There may be additional content types frequently used
depending on how the system is configured. CARIS recommends
that analysis be done once a system is in place to see if more
performance tuning can be done to get the most out of the
system.
The following text shows the configuration in the httpd.conf file
of Apache Web Server that is needed to achieve HTTP
compression:
# Modules required
LoadModule deflate_module modules/mod_deflate.so
LoadModule filter_module modules/mod_filter.so
LoadModule headers_module modules/mod_headers.so
<Location />
<IfModule mod_deflate.c>
# Compress content with the following types; add other types as needed
AddOutputFilterByType DEFLATE application/javascript image/gif image/png
image/jpeg text/css text/html
<IfModule mod_headers.c>
# Properly handle requests coming from behind proxies
Header append Vary User-Agent
</IfModule>
</IfModule>
</Location>
# Some old browsers do not handle compression
<IfModule mod_deflate.c>
BrowserMatch ^Mozilla/4 gzip-only-text/html
BrowserMatch ^Mozilla/4\.0[678] no-gzip
BrowserMatch \bMSIE !no-gzip !gzip-only-text/html
</IfModule>
# The following lines are optional. They provide configuration
# to create a log called deflate.log. It can be used to check
# that responses are in fact being compressed. Uncomment the
# lines to create the log.
#<IfModule mod_deflate.c>
# DeflateFilterNote Input instream
# DeflateFilterNote Output outstream
# DeflateFilterNote Ratio ratio
# LogFormat '%r %{outstream}n/%{instream}n (%{ratio}n%%)' deflate
# CustomLog logs/deflate.log deflate
#</IfModule>
136
Advanced Configuration Settings: Apache Tomcat
Apache Tomcat
This section refers to Tomcat 8.0. Refer to the documentation for
the version of Tomcat that you are running.
HTTP Compression on
Apache Tomcat
Compression can be set in Apache Tomcat to improve response
time and the user experience. CARIS recommends using this
technique. Apache Tomcat documentation describes how to
enable compression:
https://tomcat.apache.org/tomcat-8.0-doc/config/http.html
In short, the server.xml needs to be modified so that the HTTP
connector enables compression and should include a list of
MIME types to compress. The following example goes beyond the
default compression MIME type list that becomes available by
simply enabling compression (compression = "on", see the
Tomcat documentation). By also adding the
compressableMimeType attribute, some additional binary image
files can be included, although the default list alone will show
significant improvements.
<Connector port="8080" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443"
compression="on"
compressableMimeType="application/javascript, application/json,
image/gif, image/png, image/jpeg, text/css, text/html"/>
Tomcat Deployment
Option
This section describes a way of deploying Tomcat so that it is
separated into what is known as CATALINA_HOME and
CATALINA_BASE. The configuration is useful primarily because it
simplifies upgrading Tomcat. The binary components of Tomcat
are separated from the web application specific configuration.
This means that the web application configuration is untouched
during an upgrade.
Upgrading this deployment approach from Tomcat 7.0 to 8.0 will require that the
server.xml file in conf is replaced with the version 8.0 server.xml.
The benefit is increased if multiple instances of Tomcat are in
use. All CATALINA_BASE deployments of Tomcat will depend on
one CATALINA_HOME directory. In such multiple instances, there
would be one CATALINA_HOME directory and multiple
CATALINA_BASE directories, each with a different directory name.
The install uses the .zip archive distribution of Tomcat rather
than the installer. The Windows .zip can be obtained from:
137
The JRE_HOME environment variable should be set before attempting to
deploy Tomcat in this way. See “SET JRE_HOME VARIABLE” ON PAGE 138
(below) for instructions on how to do this.
Set JRE_HOME
Variable
1. Click Start...
2. Enter "Edit the system environment variables" in the Search program
and files text box and click Enter.
The System Properties dialog appears
3. Click the Environment Variables... button
The Environment Variables dialog appears
4. Click the New... button in the System Variables group box.
The New System Variable dialog appears
5. Type "JRE_HOME" in the Variable name text box
6. Type the path to JRE_HOME in the Variable value text box
Configuration Data
Directory
Create the following directory:
C:\CARIS\SFV\tomcat_8680
This directory will hold the configuration data. It is assigned to
the com.caris.sfv.dir Java option during the following
configuration steps.
CATALINA_HOME apache-tomcat
Extract the contents of the Tomcat .zip distribution. The
extraction directory will be similar to apache-tomcat-8.0.21.
Rename this to apache-tomcat. This is not essential but it will
help ensure that scripts that point to files in this location will
always work. This directory will be replaced in the future when
Tomcat is upgraded.
This directory will be CATALINA_HOME. This is the root of the
Tomcat installation. It is similar to the Tomcat installation
directory.
CATALINA_BASE tomcat_8680
138
A CATALINA_BASE is defined for each instance of Tomcat that will
be deployed. This is where web applications will be installed and
configuration changes are made. Create a directory named
"tomcat_8680" in the same location as the CATALINA_HOME
directory. Create the following sub-directories in it: bin, conf,
logs, temp, webapps and work.
The directory structure will now look like this:
Root
First level directory
Second level directory
Comments
C:
\apache-tomcat
This directory contains tomcat binary files,
and is the CATALINA_HOME directory.
\tomcat_8680
This directory contains tomcat_8680 web
application files. It is a CATALINA_BASE
directory.
\bin
\conf
\logs
\temp
\webapps
\work
CATALINA_BASE\conf
Copy the contents of the apache-tomcat\conf directory to
Edit the server.xml so that the connector
port is set to 8680, as in the following example.
CATALINA_BASE\conf.
<Connector port="8680" protocol="HTTP/1.1"
connectionTimeout="20000" redirectPort="8443" />
CATALINA_BASE\weba
pps
Copy the web application WAR to the webapps directory.
CATALINA_BASE\bin
Create an install.bat script in the bin directory with the
following contents:
set CATALINA_HOME=c:\apache-tomcat
set CATALINA_BASE=c:\tomcat_8680
C:\apache-tomcat\bin\service install tomcat_8680
Create an updateservice.bat script in the bin directory with
the content shown below. This script is used to set the Java
Options for the Tomcat service:
set CATALINA_BASE=c:\tomcat_8680
set CATALINA_HOME=c:\apache-tomcat
c:\apache-tomcat\bin\tomcat7.exe //US//tomcat_8680 --JvmMs "" --JvmMx "" -JvmOptions "-Dcatalina.base=%CATALINA_BASE%;-Dcatalina.home=%CATALINA_HOME%;Djava.endorsed.dirs=%CATALINA_HOME%\endorsed;Djava.io.tmpdir=%CATALINA_BASE%\temp;Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager;Djava.util.logging.config.file=%CATALINA_BASE%\conf\logging.properties;-Xmx256m;Xms256m;-Dcom.caris.sfv.dir=c:\CARIS\SFV\tomcat_8680
Note that the updateservice.bat script contains the Java
options. These can be edited if a different configuration is
desired. The example can be used as a template.
Run the install.bat script to install the Windows Service. Run
the updateservice.bat script to change the Java Options.
139
Optionally, to ensure that the Java Options have been
committed, navigate to the CATALINA_HOME\bin directory, copy
the tomcat8w.exe file and paste it in the directory. Rename it
tomcat_8680.exe and open it. The Java Options that have just
been set should be visible on the Java Options tab.
Start and Stop Tomcat
The Tomcat instance has been installed as a Windows service.
To start the service open the Windows Services console. Click
Start and type Services in the search box. The service will be
listed with the name Apache Tomcat tomcat_8680. Select it and
click the Start hyperlink. At this point the service can also be
configured to start automatically, which is appropriate for
production systems. Right click on them, select Properties and
change the Startup Type to Automatic (Delayed Start). This will
allow the service to restart automatically when the system
reboots.
The service can be stopped using the Windows Services console.
Upgrading Tomcat
In this configuration, the steps to upgrade Tomcat from one 7.0.x
release to a more recent version of 7.0.x (for example, 70.59 to
7.0.61) are as follows:
1. Obtain the latest version of Tomcat.
Use the Windows .zip distribution.
2. Stop the Tomcat services.
3. Remove the contents of the apache-tomcat directory.
4. Extract the contents of the .zip apache-tomcat-7.0.x directory to the
apache-tomcat directory
5. Start the Tomcat services.
All CATALINA_BASE deployments of Tomcat that depend on the
CATALINA_HOME, where the binary files are upgraded, will be
upgraded in this sequence of steps.
In this configuration, the steps to upgrade Tomcat from version
7.0.x to version 8.0.x are as follows:
1. Obtain the latest version of Tomcat
Use the Windows .zip distribution
2. Stop the Tomcat services
3. Remove the existing Tomcat Windows service
4. Remove the contents of the apache-tomcat directory
5. Extract the contents of the .zip apache-tomcat-8.0.x directory to the
apache-tomcat directory
6. Copy the contents of apache-tomcat\conf to CATALINA_BASE\conf
7. Edit CATALINA_BASE\conf\server.xml to set the HTTP port
140
8. Start the Tomcat services
All CATALINA_BASE deployments of Tomcat that depend on the
CATALINA_HOME, where the binary files are upgraded, will be
upgraded in this sequence of steps.
Change the Database
Port
The database communication port for Spatial Fusion Viewer
occurs on port 9002 by default. It can be changed by editing the
Tomcat context file. The context file is created when a web
application is deployed (that is, a WAR has been deployed by
Tomcat in the webapps folder). The context file can be found in
this directory:
[Tomcat Installation Folder]\conf\Catalina\[hostname]
To change the database port to 2345:
1. Find the url command in the context.xml file, for example:
url="jdbc:hsqldb:hsql://localhost/sfv"
2. To this line, add :2345 immediately after localhost, for example:
url="jdbc:hsqldb:hsql://localhost:2345/sfv"
For further information, see Apache Tomcat documentation at:
http://tomcat.apache.org/migration.html#7.0.x_to_8.0
141
Advanced Configuration Settings: Web Robots
Web Robots
Web robots are programs that automatically traverse the
internet. They are used by search engines to index the web but
they have other uses too. A file, referred to generally as
robots.txt, can be used to instruct web robots on what they
should and should not traverse. Note that web robots can ignore
the instructions in robots.txt so its use does not provide a
blocking or restrictive measure.
You can use robots.txt to instruct web robots not to traverse
the web application pages. This will provide the benefit of saving
bandwidth and keeping the web robots access requests out of
logs. The content of robots.txt that will instruct a web robot not
to visit any of the pages on a site is
User-agent: *
Disallow: /
To configure Tomcat with robots.txt the file should be placed in
[Tomcat Installation Directory]\webapps\ROOT
If Apache Web server is used to front Tomcat, it too can be
configured with robots.txt. In this case the file is placed in
[Apache Installation Directory]\htdocs
142
Advanced Configuration Settings: Secure Sockets Layer
Secure Sockets Layer
This section considers two situations in the context of secured
connections using Secure Sockets Layer (SSL):
• Securing the server that serves the web application
• Connecting the web application to secured servers
Securing a Server
When a server is secured, an encrypted link can be established
between the server and clients that connect to it. In this context
the server is the application that serves the web application.
Examples of servers are Apache Web Server and Apache
Tomcat.
Please refer to the appropriate documentation for the server that
hosts the web application. Documentation for Apache Tomcat
can be found at:
http://tomcat.apache.org/tomcat-8.0-doc/ssl-howto.html
The Java keytool command interface is used in the context of
Apache Tomcat. This is distributed with JRE. If you are creating
a self-signed certificate and need to add this to the truststore of a
client application (see “SCENARIO 2” ON PAGE 144) the -exportcert
command is used. See the following link for more information:
http://docs.oracle.com/javase/8/docs/technotes/tools/windows/
keytool.html#exportCertCmd
Documentation for Apache Web Server can be found at:
http://httpd.apache.org/docs/2.4/ssl/ssl_howto.html
143
Connecting to Secured
Servers
This section discusses connecting the web application to a
secured server. This would occur if, for example, the web
application needed to communicate with an LDAP server that is
secured with SSL (LDAPS). In this context the web application
is acting as a client.
No configuration changes are made to the web application. The
changes, if necessary, are made to the configuration of the Java
Runtime Environment (JRE).
We consider two scenarios.
• Scenario 1: The secured server has a certificate issued by a
Certificate Authority.
• Scenario 2: The secured server has a self-signed certificate.
Scenario 1
If the secured server has a public key certificate that is issued by
a Certificate Authority there should not be a need to make
configuration changes to the JRE.
Scenario 2
Certificates are needed to establish trust between two entities.
In some cases an organization may create its own certificates,
referred to as self-signed public key certificates. These
certificates will not be available to a client application by
default. A self-signed certificate will need to be explicitly
imported into the configuration of a client in order to establish
the trust and to allow secure communication between the client
and server. This will be done by the administrator of the client.
A public key certificate needs to be obtained for each of the
secured servers that the web application will be connected to.
144
You should contact the administrator of the secured servers and
ask for the self-signed public key certificates.
If you are the administrator of the server and the client you
should read the section about securing the server. You will find
information on how to create self-signed certificates at the links
provided.
The self-signed certificate needs to be imported into the Java
keystore. This is known as the truststore when used in the
client-side of the connection. This keystore will contain
certificates that the web application trusts. The import step is
accomplished using the -importcert command of the keytool
command interface. See the following link for more information:
http://docs.oracle.com/javase/8/docs/technotes/tools/windows/
keytool.html#importCertCmd
It is not recommended to use the default keystore as the
truststore. The -file is used with the -importcert command to
specify the location of the truststore. If the file does not exist it is
created automatically during the import process.
It is not recommended that the location of the truststore is set
within the JRE deployment. This is to avoid a situation in which
the truststore might be inadvertently removed during an
upgrade of JRE. If the truststore is removed it can be recreated
by repeating the import process.
The following Java options are used to configure the Java
environment of the web application so it can use the truststore.
These Java options must be set.
Java Option Name
Description
javax.net.ssl.trustStore
The value of this Java option is a path to the location of the
truststore containing self-signed certificates that are trusted by the
web application. Forward slashes must be used instead of
backslashes on a Windows environment.
javax.net.ssl.trustStorePassword
The value of this Java option is the password for the truststore that
is found in the location specified by the javax.net.ssl.trustStore Java
option.
The Java options must be set with the standard syntax.
-DjavaOptionName=Value
For example, to set the location of the truststore the following
syntax would be used:
-Djavax.net.ssl.trustStore=C:/truststore/trustedcerts.jks
The Java options can be set using the Tomcat GUI application
that is used to configure the Tomcat instance that hosts the web
application. The Java options are set in the Java Options text box
that is found on the Java tab. Tomcat must be restarted after
adding the Java options.
145
146
B
Monitor User Connections
In this chapter...
TRACKING USERS IN APACHE HTTPD SERVER ............... 148
VIEW ACTIVE SESSIONS USING APACHE TOMCAT............... 149
Monitor User Connections: Tracking users in Apache HTTPD Server
Tracking users in Apache HTTPD Server
In scenarios where an Apache HTTPD Server is forwarding
requests to web applications running in servlet containers, such
as Tomcat, logging is best done at the level where all of the
requests are first received. This guarantees accuracy of
information in a single location.
The log of most interest for identifying who is accessing the
server is the access log. The access log can be found in the
Apache Server logs directory.
Apache HTTPD Server Log Directory: $APACHE_HOME/logs
Apache HTTPD Server Access Log: $APACHE_HOME/logs/access.log
Additional information on the access log and how to configure it
and perform log analysis can be found here:
http://httpd.apache.org/docs/2.4/logs.html
148
Monitor User Connections: View active sessions using Apache Tomcat
View active sessions using Apache Tomcat
Apache Tomcat Server comes with a manager web application
that allows the administrator to remotely manage the server's
web applications. As well, it provides basic functionality to view
the number of sessions open for a particular web application,
and terminate sessions if necessary.
Manager Web Application Directory: $CATALINA_HOME/webapps/
manager
URL: http://host:8080/manager/html
To authenticate, you need to ensure that your
$CATALINA_HOME/conf/tomcat-users.xml
is correctly set up. Below is a minimal example of what needs to
be set to authenticate to the manager web application:
<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
<role rolename="manager"/>
<user username="admin" password="s3cret" roles="manager"/>
</tomcat-users>
The basic syntax to see the sessions for a given web application
is as follows, where "myWebApplication" would be replaced with
the name of the web application you want to see the current
sessions for:
http://host:8080/manager/html/sessions?path=/
myWebApplication
Additional information on the manager web application and its
configuration can be found here:
http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html
149
Monitor User Connections: View active sessions using Apache Tomcat
150
C
Web Services Optimization
In this chapter...
INTRODUCTION ........................................................... 152
OPTIMIZATION GUIDELINES ........................................... 153
CONFIGURING DATA LAYERS ........................................ 154
Web Services Optimization: Introduction
Introduction
In addition to this appendix, Administrators may also find
useful optimization information in the Web Services
Optimization appendix of the CARIS Spatial Fusion Server
Reference Guide.
Marine datasets can be very dense. The web application protects
users from unintentionally causing problems with certain
services because of this high data density.
CARIS has restricted the data selection for a WFS request in the
following ways:
• SFE does not support any attribute queries of BDB™ raster
data.
• The WFS GetFeature request must include a bounding box.
Based on the bounding box, the point closest to the centre of
the bounding box is used to return feature information at that
location.
This technique prevents a user from unintentionally making a
query that could result in an excessive processing response.
Web Coverage Service is well-suited to point data and cloud
data. Data from the BDB Server can be downloaded using a
WCS.
152
Web Services Optimization: Optimization Guidelines
Optimization Guidelines
The speed and performance of the web application can be
maximized for the end user by having as few calls to a server as
possible. This can be accomplished by layers configured
according to the following principles:
• Combine all data source layers into a single WMS or WMTS
service that will be used in the creation of a Theme in the web
application. See“THEMES” ON PAGE 86 for more information.
• When layers from more than one data source are desired in a
Theme in the web application, the layers from the same data
source should be arranged consecutively if possible. See
“MINIMIZE CALLS TO DATA SOURCE” ON PAGE 154 for more information.
• When using a WMTS service, related layers can be grouped
into a single layer. When this group layer is drawn in Spatial
Fusion Viewer, the data from all layers is displayed as a
single layer.
It is important to avoid creating an individual WMS or WMTS
for each data source whenever possible, as this will increase the
number of calls to the server and thus reduce the performance of
Spatial Fusion Viewer, or a third-party client.
The draw speed of a map that is a combination of multiple
sources is only as fast as the slowest data source. See “THEMES” ON
153
Web Services Optimization: Configuring Data Layers
Configuring Data Layers
Once the service is set up in Configuring Data Layers in Spatial
Fusion Server, the configuration can be completed in Spatial
Fusion Viewer Manager. The layers in the Themes should be
organized to reduce the number of calls to the same data source.
Minimize Calls to Data Source
Creating a theme in the web application with alternating layers
from two data sources is inefficient, for these reasons:
• Time is wasted by the server in making repeated calls to the
same data source.
• Draw times will increase dramatically as each data source is
drawn more than once.
Having a single service for all related data sources is
recommended, thereby only having to create one data connection
containing all of the layers from the various data sources. The
display of these layers can be configured using themes. This will
improve the efficiency of the draw.
When different layers from the same data source are contained
in one theme, the web application will minimize the number of
draw requests being sent back to the server. If layers from one
data source are consecutive in the theme, the web application
will send one request to the server that includes all the layers in
the draw, so that only one image would be returned.
If the layers for two different connections are added in
alternating order, the client application is forced to make
multiple requests, which increases the response time for the end
user.
Each request is actually more than 24 image requests per draw
because the maps are delivered from the server to the client in
tiles. Alternating layers can thus make a much larger number of
draw requests. See the image below for examples of a random
setup and an optomized setup.
154
If a single OGC instance with consecutive layers is used, the
number of draws is greatly reduced, since each draw request
would include a list of all of the layers to be drawn at once, and
the server would combine the images together before they were
returned. This would be much more efficient, and would improve
draw speeds in comparison to the alternative.
155
Configuring Layers
To configure layers in the web application, follow this procedure:
1. Create a new data connection for the layers being configured in the
web application. The service created in the previous set of steps will be
used as the source. See “DATA CONNECTIONS” ON PAGE 70 for instructions
on configuring layers.
2. Create a theme for the new connection by selecting desired layers from
any data type already registered, and saved under a single WMS,
WMTS, WFS or WCS. See “ADD THEMES” ON PAGE 87 for instructions on
how to do this.
156
.
A single Theme can have multiple types of data layers included. As much as
possible though, layers from the same data source should be arranged
consecutively in the Theme.
3. Save the layers.
4. Assign the new theme to a role. All users with this role will see the new
theme when they access Viewer. See “”“ADD ROLES” ON PAGE 107 for
instructions on how to do this.
157
The resulting themes will minimize the response time of the
application.
158

Help - Caris

Transcription

Similar documents

Regions CD Check Viewer Installation Guide

ASE2000 Version 2 - Applied Systems Engineering Inc.

UNO-TS2 Data Sheet

Jessica Steinhauser, Kachelofen.

Sean Paul - Alex Bienstock

Extending limits of space - Geodetski zavod Celje, doo

OSS Identity Management

The ESOP Rise, Fall and Resurrection

Kids Pedal Tractor Pull