WFSRI Installation and User Guide (x download)

tastelessbeachInternet and Web Development

Nov 12, 2013 (3 years and 6 months ago)

74 views

DRAFT

DRAFT

4
-
Dimensional Weather Data Cube

Web Feature Service Reference Implementation (WFSRI)



















Version 1.1

Installation and User Guide

MIT Lincoln Laboratory


WFSRI Installation and User Guide

MIT Lincoln Laboratory



2

Table of Contents


Table of
Contents

................................
................................
................................
................................
........

2

0

Before You Start

................................
................................
................................
................................
.

3

0.1

A Note on Formatting

................................
................................
................................
...................

3

0.2

Environment Variables

................................
................................
................................
.................

3

0.2.1

Setting Environment Variables in the Bash Shell

................................
................................
.

4

0.2.2

Setting Environment Variables in the C or TC Shells

................................
..........................

4

1

WFSRI Installation

................................
................................
................................
.............................

6

1.1

Installation Prerequisites

................................
................................
................................
...............

6

1.2

Downloading the WFSRI

................................
................................
................................
..............

6

1.3

Configuring Oracle and Tomcat

................................
................................
................................
...

7

1.3.1

Configuring Oracle 11g

................................
................................
................................
........

7

1.3.2

Configuring Apache Tomcat 6.x

................................
................................
...........................

8

1.4

Installing the WFSRI Software

................................
................................
................................
.....

8

1.5

Configuring the WFSRI

................................
................................
................................
................

9

1.5.1

Configuring the WFSRI Server

................................
................................
.............................

9

1.5.2

Configuring the WFSRI Admin GUI

................................
................................
..................

11

2

WFSRI User Guide

................................
................................
................................
...........................

1
3

2.1

Overview

................................
................................
................................
................................
.....

13

2.2

Registering Producers

................................
................................
................................
.................

14

2.2.1

Programmatically

................................
................................
................................
................

14

2.2.2

via the WFSRI Admin GUI

................................
................................
................................

14

2.3

Creating Feature Tables / Types

................................
................................
................................
.

15

2.3.1

Programmatically

................................
................................
................................
................

15

2.3.2

via the WFSRI Admin GUI

................................
................................
................................

16

Appendices

................................
................................
................................
................................
.................

19

A

Annotating the Feature Type XSD

................................
................................
................................
..

19

B

Specifying the Feature Table Definition XML

................................
................................
...............

22

C

Example GetCapabilities Response XML File

................................
................................
...............

25

D

Example Feature Type Registration Properties File

................................
................................
.......

25





WFSRI Installation and User Guide

MIT Lincoln Laboratory



3

0

Before You Start



0.1

A Note on Formatting


Throughout this guide,
references to code or inputs to be made on the Linux command line

are rendered
in

monospace

text. In general, if the text is regular (i.e., not
boldfaced
), it
already exists

in a file

or is
printed
to the Linux terminal
by
the
system
.
B
oldfaced text

is
text
typed in by the user.


For example,
the following line

instructs you to type the command
c
d webapps

at the Linux command
prompt (
$
)
:


$
cd webapps


Likewise, given the following sample of code from a file, the
boldfaced

line is inserted by the user into
the file:



<bean id="memoryUserDetailsService"


class
="org.springframework.security.userdetails.memory.InMemoryDaoImpl">


<property name="userMap">


<value> LTN=LTN,ROLE_USER


LTN
PRODUCER
=LTN,ROLE_USER


AIREP=AIREP,ROLE_USER


CONSUMER1=CONS,ROLE_USER


SUBSC1=SU
BSC1,ROLE_USER


SUBSC2=SUBSC1,ROLE_USER


SUBSC3=SUBSC1,ROLE_USER


SUBSC4=SUBSC1,ROLE_USER


gabriel=seraph,ROLE_USER


</value>


</property>

</bean>




0.2

Environment Variables


This guide contains numerous references to environment variables. Taking the form
$VARIABLE_NAME
,
environment variables stan
d in for complete folder paths
. If they are set i
n the appropriate Linux
configuration file, environment variables can be used on th
e command line

in place of long directory
paths.


For example,
if you install Apache Tomcat 6.x (see Section 1.1) to your home directory (
~
), its actual
path would
probably

look something like this:


~/apache
-
tomcat
-
6.0.20


Likewise
, the path of
Tomcat’s
w
ebapps

sub
directory
would look like this:


~/apache
-
tomcat
-
6.0.20/webapps

WFSRI Installation and User Guide

MIT Lincoln Laboratory



4


However,
because you might not have installed
Tomcat
to your

home directory
,

or might not want to
have
to
remember where you installed it, you can set

an environment variable
that

points to
the directory
.
You
would then be able to use the variable in place of the full path.


For example, if you set the Tomcat installation directory to the environment variable
$TOMCAT
, the path
of the
webapps

directory
mentioned above
would be the fo
llowing
:


$
TOMCAT
/webapps


Y
ou can temporarily set environment variables,
but t
hey will cancel out if you shut down your Linux
terminal window. Thus, it is recommended that you permanently set your environment variables in
the
correct configuration files a
s instructed below.


This guide assumes you are
set
ting

environment variables

as they are introduced. If you
do not
,

you must
replace variables with
the
actual pa
ths to directories whenever they

appear in instructions.



0.2
.1

Setting Environment
Variables

in the Bash Shell


If you are using a Bash shell in your distribution of Linux, your environment variables are set in the file
.bashrc

in your home directory (
~
). To set an environment variable, open this file in a text editor of
your choice and
add the following lines at the very bottom
, substituting the correct variable name and
path
:



VARIABLE_NAME=
/
path
/to/the/folder

export VARIABLE_NAME



Thus, if you installed Tomcat to your home directory, you could set the environment variable
$TOMCAT

to
point to it by entering the following:



TOMCAT=~/apache
-
tomcat
-
6.0.20

export TOMCAT




0.2.2

Setting Environment Variables in the C or TC Shells


If you are using a C or TC shell in your distribution of Linux, your environment variables are set in the
.
cs
hrc

or
.tcshrc

file

in your home directory
(
~
). To set an environment variable, open the file in a
text editor of your choice and add the following line at the very bottom
, substituting the correct variable
name and path:



setenv VARIABLE_NAME
/
path
/to/the/folder



WFSRI Installation and User Guide

MIT Lincoln Laboratory



5

Thus, if you installed Tomcat to your home directory, you could set the environment variable
$TOMCAT

to
point to it by entering the following:



setenv TOMCAT ~/apache
-
tomcat
-
6.0.20




WFSRI Installation and User Guide

MIT Lincoln Laboratory



6

1

WFSRI Installation


Thank you for your interest in t
he Web Feature Service Reference Implementation (WFSRI) of the 4
-
Dimensional Weather Data Cube.
This
chapter

describes the process of installing and
configuring

the
WFSRI
on

Linux operating systems.



1.1

Installation Prerequisites


Before you can install the
WFSRI, the following software packages must
already be

installed on your
Linux system:




Java Development Kit


The WFSRI requires JDK 1.6.




Oracle 11g


Oracle 11.1.0.6 (11g)
must be
installed and patched

to version 11.1.0.7
. The
installation should include Oracle
XDB
, Oracle Advanced Queues, and Oracle Spatial. A g
uide
may be found at:

http://download.oracle.com/docs/cd/B28359_01/nav/portal_11.htm
.


Verify that the environment variables
$ORACLE_HOME
,

$ORACLE_SID
, and
$PATH

are set in your
.bashrc
,
.cshrc
, or
.tcshrc

configuration file, consult
ing

with your system administrator if
this is not the case.
Note the
value of
$ORACLE_
SID

for later use
.




A
pache Tomcat

6.x


Apache Tomcat 6.x must be installed and operable. If i
t is not already on
your system,

d
ownload the Apache Tomcat 6.x Core Binary distribution

from
http://apache.cs.utah.edu/tomcat/tomcat
-
6/v6.0.20/bin/apache
-
tomcat
-
6.0.20.tar.gz
. U
npack the
.tar file to a directory of your choice

and
set the environment va
riable
$TOMCAT

to point to it (see
Section 0.2

for instructions on setting environment variables). Then

run the following commands

in the Linux terminal

to c
reate the
$
TOMCAT
/logs

directory

and start Tomcat:


$
cd
$TOMCAT

$
mkdir logs

$

chmod 2755 logs

$
bin/startup.sh


R
unning the
startup.sh

script will
temporarily
set the
$CATALINA_HOME

environment
variable
. While
$CATALINA_HOME

technically points to the same directory as
$TOMCAT
,
you
should not try to
manually
set
$CATALINA_HOME

as a permanent
environment variable on your
system
.

Doing so may cause
errors

in Tomcat’s scripts.

Use
$TOMCAT

instead.


Instructions on how to configure Oracle 11g and Apache Tomcat 6.x for your WFSRI installation may be
found in Section 1.3.



1.2

Downloading the WFSRI


If

you have not already done so, you must download the WFSRI Version 1.1 .tar file and extract its
contents to their proper locations.
This .tar file includes everything you will need to configure Oracle 11g
and install the WFSRI. Note t
hat
the
WFSRI
cannot
be installed until both O
racle 11g and Apache
Tomcat 6.x have been configured
.


WFSRI Installation and User Guide

MIT Lincoln Laboratory



7

1.

Use your web browser to navigate to
https://wiki.ucar.edu/display/NNEWD/Releases
.


2.

Find and download
wfsri
-
1.1.tar
.
Extract the file to a directory of your choice. The extraction process
will create the directory
WFSRI_1.1
-
Release

(henceforth referred to as
$WFSRI_INSTALL
; see
S
ection 0.2 for instructions on setting environment variables
)
,

containing
three files and t
hree

sub
-
directories
:


$WFSRI_INSTALL/wfsri
-
1.1.0.jar

$WFSRI_INSTALL
/
wfsri
-
1.1.0.war

$WFSRI_INSTALL
/
WFSA
dmin
-
1.1.war

$WFSRI_INSTALL/conf/

$WFSRI_INSTALL/samples/

$WFSRI_INSTALL/sql/



1.3

Configuring Oracle and Tomcat


After you have downloaded the WFSRI
.tar file, you must properly configure both Oracle 11g and
Apache Tomcat 6.x b
e
fore you can proceed with installation.



1.
3
.1

Configuring Oracle 11g


In order to configure Oracle 11g for use with the WFSRI, you must have
downlo
aded the WFSRI .tar file
from

https://wiki.uscar.edu/display/NNEWD/Releases
. See Section 1.2 for details.


1.

Open a Linux terminal and c
hange the directory to
your
$
WFSRI_
INSTALL
/sq
l/install

directory.


$
cd
$WFSRI_
INSTA
LL
/sql/install


2.

Install the WFSRI Oracle package by typing the following command, replacing the placeholders as
indicated in the table below:


$
sqlplus "
<sys
user
>/<syspass> as sysdba"

@wfs
_install <user
> <pass>


<wfsTablespace> <wfsTempTablespace>


Placeholder

Replace With

<sysuser>

Your Oracle DBA system username

<syspass>

Your Oracle DBA system password

<
user
>

Your desired
WFS database

username

<pass>

Your desired WFS database
password

<wfsTablespace>

The name for the WFS tablespace that will hold the WFSRI
metadata. While this can be
set to an existing tablespace (e.g.,
SYSAUX
), we recommend using a distinct tablespace for the WFSRI
metadata. It will be created by the installation script.

<wfsTempTabl
espace>

The name for the tablespace to be used by the WSFRI for writing
temporary files and logs. It will be created by the installation script.

WFSRI Installation and User Guide

MIT Lincoln Laboratory



8


The
@
wfs_install

script will create the new user and install all required WFSRI metadata tables
and libraries

into its user space.


3.

Test the installation by l
ogging into Oracle as the newly
created user:


$
sqlplus <user>/<pass>


Type the following command:


sql>
select table_name from user_tables;


This

response should print to your screen:


TABLE_NAME

------------------------------

WFS_
PRODUCER

WFS_FEATURETYPE

WFS_FEATURETYPE_QUEUE

WFS_SUBSCRIBER

WFS_ADMINFEATURE

WFS_FEATURETABLEMETADATA

ERRLOG

LOGGER


8 rows selected.


4.

If the printed response does not match the above lines, you can check the installati
on log file for
errors:
$WFSRI_INSTALL/sql/install
/
install<date>_<time>.log
.


5.

Assuming there were no errors, y
ou may log out of Oracle.


sql>
exit



1.
3
.2

Configuring Apache Tomcat 6.x


Apache Tomcat 6.x must be configured to have a cache size of 1GB in order to operate correctly with the
WFSRI.
Use a text editor to a
dd the following line of code to
$
TOMCAT
/bin/setenv.sh
, creating the
file if it does not already exist:


JAVA_OPTS="
$
JAVA_O
PTS

Xmx1024M

Dsun.io.useCanonPrefixCache=false"



1.4

Installing the WFSRI Software


The WFSRI can be installed onto a Linux system only after both Oracle 11g and Apache Tomcat 6.x have
been properly configur
ed. Please refer to S
ection 1.3

and ensure those steps have been completed before
proceeding.


1.

Move the

two .war files
you downloaded and extracted in Section 1.2 from the
$WFSRI_
INSTALL

folder to Tomcat’s
webapps

folder.

WFSRI Installation and User Guide

MIT Lincoln Laboratory



9


$
mv $WFSRI_
INSTALL
/
*
.war $
TOMCAT
/webapps


2.

Moving the

.war
file
s

into Tomcat’s
webapps

directory should have automatically created
two new
sub directories named after the two files:

the

webapps/w
fsri
-
1.1.0

directory

(henceforth referred
to as
$WFSRI_HOME
)
, and the
webapps/
WFSAdmin
-
1.1

directory

(henceforth referred to as
$WFSRI_ADMIN
)
. To check, navigate to the
webapps

directory and list its contents.


$
cd $
TOMCAT
/webapps

$
ls


Among other files and folders,
wfsri
-
1.1.0

and

WFSA
dmin
-
1.1

(not to be confused with

the .war
files
) should be listed. If
they

are
, skip to Step 3. If

not, restart Tomcat

to build the directories
.


$
$TOMCAT
/bin/shutdown.sh

$
$TOMCAT
/bin/startup.sh


3.

Move the
conf

directory from its location in the
$WFSRI_INSTALL

folder to the
$WFSRI_HOME

folder.


$
mv $
WFSRI_INSTALL/conf $WFSRI_HOME


4.

The environment variable
$CONFIG_DIR

must

be permanently set
so it points to the location of the
conf

folder. If you are using
a

B
ash shell, add the following lines to the end of the
.bashrc

file in
your home directory
:


CONFIG_DIR=
$WFSRI_HOME
/conf

export CONFIG_DIR


If you are using
a

C

or

TC

shell, add the following line to the end of the
.cshrc

or
.tcshrc

file in
your home directory
:


setenv CONFIG_DIR
$WFSRI_HOME
/conf


Note that the environment variable
$WFSRI_HOME

must already be set on your system prior to
completing this step. See Section 0.2 for more information.



1.5

Configuring the WFSRI


Once all the WFSRI files and folders are in their correct locations, the final step of installation is to
configure the
WFSRI Server and WFSRI Administration UI for your local system.



1.5.1

Configuring the WFSRI Server


1.

Using your text editor of choice, e
dit the
$WFSRI_HOME/conf/wfsri.properties

file to
configure

the local properties of your WFSRI
server
, setting each of the va
riables as indicated
:




brokerURLActivemq
: The URL for the ActiveMQ broker that will be used for your WFSRI
in
stance to deliver JMS messages.

WFSRI Installation and User Guide

MIT Lincoln Laboratory



10



brokerURLProxy
: If necessary, the proxy URL for the ActiveMQ broker. If there is no proxy,
this field should be lef
t blank.




oracle.dataSource.driverClassName
: The JDBC driver that will be used to connect to the
Oracle data source. You will not need to change this unless you reconfigured where Jetty is
running.




oracle.dataSource.url
:

The URL for your Oracle data store
. This should take the following
form:


jdbc:oracle:thin:@<servername>:1521:orcl


Replace
<servername>

with the name of the server on which Oracle is installed. Change the
default port number from
1521

if your server uses a different port, and the default
Oracle SID
from
orcl

if your server is otherwise identified.




oracle.dataSource.username
: The username you created when you configured Oracle for
the WFSRI (
<user>

above).




oracle.dataSource.password
: The password you created when you configured Oracle for

the WFSRI (
<
pass
>

above).




wfs.url
: The URL to which the WFSRI server will be deployed. This is the address the WFSRI
clients and Admin UI will point to.




wfs.transportFactory
: The transport factory that should be used for the WFSRI. You may
leave this fi
eld alone.


2.

Since the WFSRI Version 1.1 is not yet integrated with an LDAP service for authenticating
username/password combinations, you must manually add username/password pairings to the
$WFSRI_HOME/WEB
-
INF/CamelContext.xml

file. Using your text editor

of choice, open this file
and find the
memoryUserDetailsService

bean, which lists the username/password pairs:



<bean id="memoryUserDetailsService"


c
lass="org.springframework.security.userdetails.memory.InMemoryDaoImpl">


<property name="userMap">



<value> LTN=LTN,ROLE_USER


LTN
PRODUCER
=LTN,ROLE_USER


AIREP=AIREP,ROLE_USER


CONSUMER1=CONS,ROLE_USER


SUBSC1=SUBSC1,ROLE_USER


SUBSC2=SUBSC1,ROLE_USER


SUBSC3=SUBSC1,ROLE_USER


SUBSC4=SUBSC1,ROLE_USER


</value>


</property>

</bean>



WFSRI Installation and User Guide

MIT Lincoln Laboratory



11

Add in any new username/password pairs you wish to the list, using the following format:


username=password,ROLE_USER


Thus, adding a new user named “gabriel” with the password “seraph” would
require the following
change:



<bean id="memoryUserDetailsService"


class="org.springframework.security.userdetails.memory.InMemoryDaoImpl">


<property name="userMap">


<value> LTN=LTN,ROLE_USER


LTN
PRODUCER
=LTN,ROLE_USER


AIREP
=AIREP,ROLE_USER


CONSUMER1=CONS,ROLE_USER


SUBSC1=SUBSC1,ROLE_USER


SUBSC2=SUBSC1,ROLE_USER


SUBSC3=SUBSC1,ROLE_USER


SUBSC4=SUBSC1,ROLE_USER


g
abriel=seraph,ROLE_USER


</value>


</prop
erty>

</bean>



3.

Restart Tomcat to execute the changes made to the various configuration files.


$
$TOMCAT
/bin/shutdown.sh

$
$TOMCAT
/bin/startup.sh



1.5.2

Configuring the WFSRI

Admin

GUI


The correct JDBC parameters must be set in the Admin
G
UI’s
jdbc.properties

file so that it can
connect to the WFSRI server.


1.

Using your text editor of choice, e
dit the
$WFSRI_
ADMIN
/
WEB
-
INF
/
classes/jdbc
.properties

file to configure

the local properties of your WFSRI
server
, setting each of the variables as indicated
:




jdbc.driver
ClassName
: The JDBC driver that will be used to connect to the Oracle data
source. You will not need to change this unless you reconfigured where Jetty is running. This
should be the same as the
oracle.dataSource.driverClassName

property configured in

S
ect
ion

1.5.1 above.




jdbc.host
:
The name of the server on which Oracle is installed.




jdbc.port
: The port used by the Oracle server,
1521

by default.




jdbc.sid
: The Oracle database identifier (SID) for your Oracle server,
orcl

by default.




jdbc.driver
: The Oracle driver,
thin

by default.


WFSRI Installation and User Guide

MIT Lincoln Laboratory



12



jdbc
.username
: The username you created when you configured Oracle for the WFSRI
(
<user>

above), identical to the parameter set for
oracle.dataSource.username

in Section
1.5.1

above
.




jdbc
.password
: The password you c
reated when you configured Oracle for the WFSRI
(
<pass>

above), identical to the parameter set for
oracle.dataSource.
password

in Section
1.5.1

above
.


2.

Restart Tomcat to execute the changes made to the configuration file.


$
$TOMCAT
/bin/
shutdown.sh

$
$TOMCAT
/bin/startup.sh


WFSRI Installation and User Guide

MIT Lincoln Laboratory



13

2

WFSRI User Guide


The Web Feature Service Reference Implementation
(WFSRI)
is

a test platform for publishing
GML
1
-
formatted

data
to
and retrieving it fr
om the 4
-
Di
men
s
ional Weather Data Cube.
Specifically
, it allows
users to register
datasets
to an Oracle database
on a W
eb Feature Server, using a Java

API
2

to manipulate
the data
.



2.1

Overview


Each of t
he datasets
registered to a Web Feature Server
is known as a

Feature
,
is
classified by
Feature
Type
,

an
d is stored in a

Feature Table
:



1.

Features
are the basic blocks of data stored in
the

database. They
can
represent any finite dataset
that a user might want to store. A
s such
,

they are very flexible;

a

Feature can

represent virtually
anything,

from
an office chair,
to
a lightning strike,
to a plane

traveling from one city to another.


A Feature is comprised of a set of attributes that
distinguish

it from other

Features of the same
type
.
T
o tell two aircraft apart
, for example,

it is necessary to
know

each plane’s operating airline,
flight number, origin city, destination terminal, time of departure, and so forth.


2.

Feature Types
serve two key roles:
They

classify Features and
they

determine the template off
which Features are built.


1.

As its name impli
es,
a
Feature Type
define
s

a

“type” of
Feature

stored in a database
. For
example,
if
an airport
terminal
wanted to store the data on all the planes that pass through, it
could create the Feature Type
flight

in its WFS database
, categorizing all the flights

beneath it
and storing them in the sa
me
flight

Feature Table
.


2.

Feature Types also serve as templates that define all the attributes a new Feature must be
registered with before it is stored. The Feature Type
flight
, for example, might require that all
new
ly registered Features of type
flight
have the “airline,” “
flight
number,” “origin,”
“destination,” “departure time,”
and “arrival time


attributes
.



3.

Feature
Tables

are the
Oracle database tables used to store

Features.

They are named for
each

Feature Type
,

and are comprised of rows and columns, much like a spreadsheet. The Feature
Table for the
flight
Feature Type, for example, would have a column for each attribute the
flight

Features have: “airline,” “flight number,” “origin,” and so on. Eac
h row
would then
represent one
Feature instance

in this case,
the data detailing

one particular

plane
.


The WFSRI
is

a toolset for moving and tracking
Features
.

It comes with the

limited
-
functionality
WFSRI
Admin GUI

and support for a handful of standardiz
ed
WFS operations
:


1.

The
GetCapabilities

operation
determine
s

what Feature

Types are registered with the server
.

2.

The
DescribeFeatureType

operation

lists

the

attributes required to create a new Feature of a
given Feature
Type
.

3.

The
GetFeature

operation

queries

the server for all available data

on specific Features.




1

Geography Markup Language, a geospatially focused variant of the common XML format.

2

Application Programming Interface, a set of code snippets that can be used to accomplish specific tasks.

WFSRI Installation and User Guide

MIT Lincoln Laboratory



14

4.

The
Transaction
(
I
nsert)

operation
registe
r
s

new Features

to

a Feature Table
.


The remaining sections

in this chapter detail how to use the Admin GUI
and WFS operations to:


1.

Register (create)
a Producer: a database user account that can manage Feature Tables.

2.

Create a Feature Table, registering a new Feature Type in the process (since Feature Types are
defined simply by a Feature Table’s name and stored attributes).

3.

Insert new Features of a giv
en Feature Type into the appropriate Feature Table.



2.2

Registering Producers


Before you can manipulate data on the Web Feature Server’s Oracle database, you must first create a
Producer

user account. The WFSRI uses Producer accounts to create and manag
e Feature Types and
Tables.


Registering a Producer can be done either programmatically or through the WFSRI Admin GUI.



2.2.1

Programmatically


If you are a software engineer with Java experience, you can register Producers programmatically,
bypassing th
e need for the WFSRI Admin GUI.


1.

Include in the classpath the
wfsri
-
1.1.0.jar

file from the
$WFSRI_INSTALL

directory.


2.

Instantiate an instance of
edu.mit.ll.wfsri.admin.ProducerAdministrator
.


3.

Execute the
registerProducer(String, String)

method,
passing to it



The username of the

new

Producer as a String



The password of the

new

Producer as a String



2.2.2

via the WFSRI Admin GUI


Producers can also be registered
using the WFSRI Admin GUI, although this method can be slower if
used to register a la
rge number of producers one at a time.


1.

Open the WFSRI Admin GUI by navigating to its installed location on your Tomcat server. This will
most likely be
http://localhost:8080/WFSAdmin
-
1.1/
.

You should be
presented with the tool’s Login
screen.


2.

Click on the “Register a new Producer” link at the bottom of the login pane.


3.

Fill in a desired username and password for the new Producer, and click “Register Producer.”



WFSRI Installation and User Guide

MIT Lincoln Laboratory



15

2.3

Creating Feature Tables / Types


In th
e current implementation of the WFSRI, registering new Feature Types is a two
-
tiered

process. First,
a new database table must be created in the Oracle database

the Feature Table

with the name of the
Feature Type and columns for the various attributes that

will define the
stored Features
. Second, the XML
code for that table must be appended with a selection of additional properties

standard to all WFS
implementations, “registering”
the Feature Type

with the server so that future queries can find it.


As with the Producer registration process, Feature Tables and Types can
be created either

programmatically or through the WFSRI Admin GUI.



2.3.1

Programmatically


If you are a software engineer with experience

in Java programming and XML formatting
, you
can create
Feature Tables

and register Feature Types

programmatically, bypassing the need for the WFSRI Admin
GUI.


Fir
st, you must create the Feature Table in the database. This requires passing in either a mapping file
(i.e., a Feature Table Definition XML file) or an annotated Feature Type
XML Schema Definition

(XSD)
with the requisite mapping information.


1.

Include in t
he classpath the
wfsri
-
1.1.0.jar

file from the
$WFSRI_INSTALL

directory
.


2.

Instantiate an instance of
edu.mit.ll.wfsri.admin.featuretable.FeatureTableAdministrator
.


3.

Execute the
reifyFeatureTable(String, File)

method, passing to it



The username of the Produ
cer as a String



The annotated Feature Type XSD as a
java.io.File

instance


See
Appendix A for information on preparing the Feature Type XSD.


4.

Alternatively,
e
xecute the
reifyFeatureTable(String)

method, passing to it

t
he
fully qua
lified
filename (in the co
ntext of the classpath) of the Feature Table Definition XML as a String.


See Appen
dix B for information on

preparing the Feature Table Definition XML.


Once the Feature Table has been created, you
can

register the Feature Type.


1.

Include in the classpath

the
wfsri
-
1.1.0.jar

file from the
$WFSRI_INSTALL

directory.


2.

Instantiate an instance of
edu.mit.ll.wfsri.admin.FeatureTypeAdministrator
.


3.

Execute the
registerFeatureType(RegisterFeatureType)

method, passing to it an instance
of
edu.mit.ll.wfsri.admin.Regi
sterFeatureType
.


The
RegisterFeatureType

instance includes the following
required

elements
, which should be
contained in a separate “properties” file with key value pairs denoting each element
:


WFSRI Installation and User Guide

MIT Lincoln Laboratory



16



producerId



the database id returned by the
ProducerAdminis
trator.registerProducer
. For example,
20
.




featuretypeName



the name of the Feature Type. For example,
RunwayAssignment
.




featuretypeURL



the namespace URI for the Feature Type. For example,
http://www.faa.gov/tfdm/1.0
.




featuretypeDescFile



the XML use
d with a
GetCapabilities

response. Provided as a
java.io.File

instance. For example,
src/test/resources/xml/get
-
capabilities/tfdmRunwayAssignment1.xml
.


See Appendix
C

for an example
GetCapabilities

response XML file.




describeFeaturetypeFile



the Feature Type XSD used with a
DescribeFeatureType

response. Provided as a
java.io.File

instance. For example,
sr
c/test/resources/xsd/parsing/tfdmRunwayAssignment.xsd
.




srsNS



the spatial reference system used by the Feature Type. For example,
urn:og
c:def:crs:ESPG::4235
.




schemaName



the username of the Producer as a String. For example,
GABRIEL
.




tableName



the name of the Feature Table. For example,
RUNWAYASSIGNMENT
.




pKeyCol



the primary key of the Feature Table. For example,
ID
.




pSpatialCol



the primary spatial column of the Feature Table. For example,
LOCAT
I
ON
.




gml31



set to
true

to indicate that Geometry elements are to be considered GML 3.1.x
compliant.


See Appendix D

for an example Feature Type Registration Properties file.



2.3.2

via
the WFSRI Admin GUI


You can also create Feature Tables and register new Feature Types via the WFSRI Admin GUI, although
this method can be far slower when registering a large number of new Feature Types, as each Table and
Type must be created one at a tim
e.


Note that when creating a Feature Table in the WFSRI Admin GUI, you must use an Annotated Feature
Type XSD; you may not prepare a separate Feature Table Definition XML for use in place of the XSD.


1.

Open the WFSRI Admin GUI by navigating to its installed location on your Tomcat server. This will
most likely be
http://localhost:8080/WFSAdmin
-
1.1/
. You should be presented with the tool’s Login
screen.


WFSRI Installation and User Guide

MIT Lincoln Laboratory



17

2.

Log in as a previously created Producer by entering the Producer’s username and password and
clicking “Login.” Note that the password is case sensitive.


3.

From the primary interface, click on the
Feature Tables

tab t
o open the F
eature Tables management
scr
een.


4.

Select the Feature Table’s Producer from the drop
-
down box
on the screen’s right
-
hand side
and click
“Register Feature Table.”


5.

On the page that appears, e
ither select a previously uploaded file from the Admin GUI’s cache or
upload a new Annotated Fe
ature Type XSD

to the cache. This schema will determine
the structure of
the new Table.


See Appendix A for information on preparing a Feature Type XSD.


6.

Click on the “Register Feature Table” button to create the new Feature Table.


With the Table created,

you may now register its associate
d Feature Type.


1.

From the primary interface, click on the
Register Feature Type

tab to open the Register Feature
Type form.


2.

Fill out each field under the “Feature Type Information” header as follows:


a.

Feature Type Name



The name of the Feature Type. This should correspond to the name in the
Feature Type Description XML file (i.e., the name that is returned on a
GetCapabilities

WFS
request).
See Appendix C for an example
GetCapabilities

response file.

For example,
RunwayA
ssignment
.


b.

Feature Type URL


The location of the Feature Type’s namespace. For example,
http://www.faa.gov/tfdm/1.0
.


c.

Feature Type Alias


An optional alias for the Feature Type, for use within the WFSRI Admin
GUI.


d.

Feature Type Description


The XML fil
e that is returned on a
GetCapabilities

WFS
request.
See Appendix C for an example
GetCapabilities
response file.
For example,
tfdmRunwayAssignment1.xml
.


e.

Describe Feature Type (XSD file)


The XML Schema detailing the various attributes

returned
for a
DescribeFeatureType

WFS request. For example,
tfdmRunwayAssignment.xsd
.


f.

SRS Namespace


The spatial reference system to be used by the Feature Type. You may search
through all available reference systems by typing “all” in the search box and clicking
“Search
List.” Select your desired spatial reference system from the drop
-
down box.


g.

SRS Namespace Alias


An optional alias for the SRS Namespace, for use within the WFSRI
Admin GUI.


h.

Other


Click the “gml31” checkbox to indicate that geometry elements s
hould be considered
GML 3.1.x compliant.

WFSRI Installation and User Guide

MIT Lincoln Laboratory



18


3.

Fill out each field under the “Feature Table Information” header as follows:


a.

Feature Table Location


The location of the Feature Table schema uploaded when creating the
Feature Table.


b.

Feature Table Name


Select

the Feature Table from the drop
-
down box. Doing so will
automatically fill in the rest of the form.


4.

Click the “Register Feature” button at the bottom of the page to register the new Feature Type.



WFSRI Installation and User Guide

MIT Lincoln Laboratory



19

Appendices



A

Annotating the Feature Type XSD


Note: Th
e current implementation of the WFSRI leverages Oracle XML Database annotation syntax to
annotate the Feature Type XSD. An example of how the attributes are utilized in an XSD can be found at
http://download.oracle.com/docs/cd/B28359_01/appdev.111/b28369/apphxdb.htm#BABHJEDH
. The
following guidelines detail how to insert such cues into a Feature Type XSD.


1.

Use the namespace prefix “
xdb
” and the URI “
http
://xmlns.oracle.com/xdb
” for the Oracle
XML Database.
For example:



<xs:schema targetNamespace=
http://www.faa.gov/tfdm/1.0


xmlns:tfdm=
http://www.faa.gov/tfdm/1.0



xmlns:xdb=
http://xmlns.oracle.com/xdb




attributeFormDefault="unqualified" version="1.0">



2.

The F
eature
T
ype is a root element in the XSD, annotated with the


xdb:defaultTable


attribute.
The value should be 27 characters or less.

F
or example:



<xs:element name="RunwayAssignmentFeature"


type="tfdm:RunwayAssignmentFeatureType"


substitutionGroup="tfdm:AbstractTfdmFeature"


xdb:defaultTable="RUNWAYASSIGNMENTFEATURE"
/>



The v
alue of this

attribute
will

be the name of
the F
eature
T
able in the database.


3.

In the XSD, the Feature Type’s datatype is
complexType
, any and
all

of whose elements and/or
att
ributes should be annotated with the “
xdb:SQLName

attribute.

For example:



<xs:
complexType name="RunwayAssignmentFeatureType">


<xs:complexContent>


<xs:extension base="tfdm:AbstractTfdmFeatureType">


<xs:sequence>


<xs:element name="flight"

type="xs:string" minOccurs="1"


xdb:SQLName="FLIGHT"
>


</xs:e
lement>


<xs:element name="assignment" type="tfdm:AssignmentType"


minOccurs="1" maxOccurs="unbounded">


</xs:element>


<xs:element name="explanation" type="xs:string" minOccurs="1"


xdb:SQLName="EXPLANATION">


</xs:element>

WFSRI Installation and User Guide

MIT Lincoln Laboratory



20


<xs:element name="location" type="tns:L
ocation"


xdb:SQLName="LOCATION"

xdb:SQLType="SPATIAL">


</xs:element>


<xs:element name="issueTim
e" type="xs:dateTime"


xdb:SQLName="ISSUETIME"
>


<
/xs:element>


</xs:sequence>


</xs:extension>


</xs:complexContent>

</xs:complexType>



The

values of these
attribute
s

will be the names of the F
eature
T
able
’s
columns in the database.


4.

The element or attribute
may

not be a reference to an element

or

attribute defined elsewhere
,

in this or
another XSD.

For example:



<xs:complexType name="Location">


<xs:complexContent>


<xs:extension base="gml:AbstractFeatureType">


<xs:sequence>


<!
--

Reference not permitted
--
>


<
xs:element ref="gml:Point"/>


</xs:sequence>


</xs:extension>


</xs:complexContent>

</xs:complexType>



5.

The value of the “
type


attribute of
a given

element
will

be

used to determine the datatype of
its

F
eature
T
able column in the database.

F
or
example:



<xs:complexType name="RunwayAssignmentFeatureType">


<xs:complexContent>


<xs:extension base="tfdm:AbstractTfdmFeatureType">


<xs:sequence>


<xs:element name="flight"

type="xs:string"

minOccurs="1"


xdb:SQLName="FLIGHT">


</xs:element>

...


</xs:sequence>



</xs:extension>



</xs:complexContent>

</xs:complexType>





WFSRI Installation and User Guide

MIT Lincoln Laboratory



21

6.

There must be one, and only o
ne, spatial element

annotated with


xdb:SQLType='SPATIAL'
”.
For
example:



<xs:complexType name="RunwayAssignmentF
eatureType">


<xs:complexContent>


<xs:extension base="tfdm:AbstractTfdmFeatureType">


<xs:sequence>

...


<xs:element name="location" type="tns:L
ocation"


xdb:SQLName="LOCATION"
xdb:SQLType="SPATIAL"
>

...


</xs:sequence>


</xs:extension>


</xs:complexContent>

</xs:complexType>



7.

The “
xdb:SQLType


may not be used for any non
-
spatial element or attribute.

For example:



<xs:complexType name="RunwayAssignmentFeatureType">


<xs:complexContent>


<xs:extension base="tfdm:Abs
tractTfdmFeatureType">


<xs:sequence>


<!
--

'xdb:SQLType' not permitted here.
--
>


<xs:element name="flight"

type="xs:string" minOccurs="1"


xdb:SQLName="FLIGHT">


</xs:element>

...


<!
--

Nor here.
--
>


<xs:
element name
="issueTime" type="xs:dateTime"


xdb:SQLName="ISSUETIME">


</xs:element>


</xs:sequence>


</xs:extension>


</xs:complexContent>

</xs:complexType>






WFSRI Installation and User Guide

MIT Lincoln Laboratory



22

B

Specifying the Feature Table Definition XML


Note:
The sample
Feature Table Definition schemas
referenced in the following examples
can
all
be
found in
the
$WFSRI_INSTALL/samples/

directory
.


1.

Specify the root element, a Feature Schema. For example, from
runwayAssignment.xml
:



<nnew:FeatureSchema xmlns:nnew=
http://www.faa.gov/wfs/admin/1.0


xmlns:xsi=
http://www.w3.org/2001/XMLSchema
-
instance


xmlns:xlink=
http://www.w
3.org/1999/xlink


xsi:schemaLocation="http://www.faa.gov/wfs/admin/1.0



../../../../../../wfsri
-
bindings/schemas/gov/faa/wfs/admin/


1.0.0/featureTableDefinition.xsd">



2.

For each Feature Table to be created in the database, specify the table’s metad
ata. All examples are
taken from
runwayAssignment.xml
.



<
nnew:FeatureTable

xlink:href="/xml/parsing/runwayBase.xml">



a.

Specify whether the table definition depends on a Base Table Definition XML.



<nnew:FeatureTable
xlink:href="/xml/parsing/runwayBase.xml"
>



b.

Specify the
schema name. This should be identical to the Producer’s
username. The string value
is limited to uppercase
d

alpha and numeric characters
,

and the underscore (_).



<nnew:schemaName>
GABRIEL
</nnew:schem
aName>



c.

Specify the table name. This is the name to use in the Oracle database. This element is optional. If
it were omitted, the name defaults to the value of the XSD name, in uppercased letters. If it were
included, the
string value is limited to upperc
ased alpha and numeric characters and the
underscore (_).



<nnew:tableName>
RUNWAYASSIGNMENT
</nnew:tableName>



Given this example, because the XSD is named “
runwayAssignment.xml
,”
<nnew:tableName>

could be omitted
,

and the table name would remain

RUNWAYA
SSIGNMENT
”.


WFSRI Installation and User Guide

MIT Lincoln Laboratory



23

d.

Specify the XSD name. This is the name of the Feature Type element as it appears in the Feature
Type XSD and as it will appear in Feature Type XML instances. The string value may not be
empty, and may not exceed 27 characters.



<nnew:xsdName>
RunwayAssignment
</nnew:xsdName>



e.

Specify the XSD namespace URI(s). These are the namespace prefix and URI pairs as they
appear in the Feature Type XSD and as they will appear in Feature Type XML instances. The
string value may not be empty.



<
nnew:xsdNamespaceURI>
tfdm='http://www.faa.gov/tfdm/1.0'


gml='http://www.opengis.net/gml'
</nnew:xsdNamespaceURI>



Ensure that each namespace prefix used in the XSD Names of the Feature Table Columns is
defined in this value. Delimit the pairs using a si
ngle space.


3.

For each element or attribute in the FeatureType type to be extracted as a database table column,
specify the metadata for the Feature Table Column.

All examples are taken from
runwayAssignment.xml
.



<nnew: FeatureTableColumn>



a.

Specify the column name. This is the name to use in the database. The
string value is limited to
uppercased alpha and numeric characters and the underscore (_).



<
nnew:columnName>
FLIGHT
</nnew:columnName>



b.

Specify the column datatype. This is used to indi
cate whather this
FeatureType type
element or
attribute is a spatial entity (“
Spatial
”)
. The default value is that it is not (“
Other
”). As such, its
value may be an empty string.

For example, for the “
FLIGHT
” column:



<nnew:columnDatatype/>



For the “
LOCATION
” column:



<nnew:columnDatatype>
Spatial
</nnew:columnDatatype>



c.

Specify the XSD name. This an XPath path expression, relative to the Feature Type tag (in this
example,
<tfdm:RunwayAssignment>
),

to the FeatureType type element or attribute as it
WFSRI Installation and User Guide

MIT Lincoln Laboratory



24

ap
pears in the Feature Type XSD and as it will appear in Feature Type XML instances. The string
value may not be empty.



<nnew:xsdName>
tfdm:
flight
</nnew:xsdName>

<nnew:xsdName>
./tfdm:location
</nnew:xsdName>

<nnew:xsdName>
tfdm:location/gml:Point@srsName
</nne
w:xsdName>



d.

Specify whether this is an XSD attribute (“
true
”).
The default value is that it is not (“
false
”).
As such, its value may be an empty string.

For example, for the “
FLIGHT
” column:



<nnew:
xsdAttribute
/>



For the “
SRSNAME
” column:



<nnew:
xsdAttribute
>
true
</nnew:
xsdAttribute
>



e.

Specify the XSD
datatype
. This is the XML schema datatype of the FeatureType type element or
attribute as it appears in the Feature Type XSD. The string value may not be empty.



<nnew:xsdDatatype>
string
</nnew:xsdDat
atype>



4.

If the Feature Table Definition depends on a Base Table Definiton XML, specify that XML.


a.

Specify the root element, a Base Table. For example, from
runwayBase.xml
:



<nnew:BaseTable xmlns:nnew=
http:
//www.faa.gov/wfs/admin/1.0


xmlns:xsi=
http://www.w3.org/2001/XMLSchema
-
instance


xsi:schemaLocation="http://www.faa.gov/wfs/admin
/1.0


../../../../../../wfsri
-
bindings/schemas/gov/faa/wfs/admi
n/


1.0.0/baseTableDefinition.xsd">



b.

Specify whether this table definition depends on another Base Table Definition XML. For
example, from
runwayBaseTest.xml
:



<nnew:BaseTable xmlns:nnew=
http://www.faa.gov/wfs/admin/1.0


xmlns:xsi=
http://www.w3.org/2001/XMLSchema
-
instance


xmlns:xlink="http://www.w3.org/1999/xlink"


xsi:schemaLocation="h
ttp://www.faa.gov/wfs/admin/1.0


../../.
./../../../wfsri
-
bindings/schemas/gov/faa/wfs/admin/


1.0.0/baseTableDefinition.xsd"


xlink:href="/xml/parsing/test.xml"
>


WFSRI Installation and User Guide

MIT Lincoln Laboratory



25


c.

For each element or attribute in the Base type to be extracted as a database table column, specify
the metadata for the Feature
Table Column. See Step 3, above.



C

Example GetCapabilities Response XML File


When programmatically registering a new FeatureType (as in Section 2.3.1), you must pass in a series of
properties further defining the FeatureType. One of these properties is
a pointer to a Capabilities file, a
small file containing the response that the Web Feature Server should make when it receives a
GetCapabilities

query. A
GetCapabilities

response file should something like this:




<?xml version="1.0" ?>

<wfs:FeatureType
xmlns:wfs="http://www.opengis.net/wfs">


<Name xmlns:tfdm="http://www.faa.gov/tfdm/1.0">


tfdm:TfdmFlightStatusFeature</Name>


<Title>TFDMFLIGHTSTATUSFEATURE</Title>


<SRS>SDO:4326</SRS>

</wfs:FeatureType>




D

Example Feature Type
Registration Properties File


When programmatically registering a new FeatureType (as in Section 2.3.1), you must pass in a series of
properties further defining the FeatureType. Together, these properties can b
v
e encased in a Properties
file, like the one

below:



# Table/Feature Type Registration File


producerId = 20

featuretypeName = RunwayAssignment

featuretypeURL = http://www.faa.gov/tfdm/1.0

featuretypeDescFile = $PATH
/tfdmRunwayAssignment1.xml

describeFeatureTypeFile = $PATH/
tfdmRunwayAssignment.xsd

srsNS = urn:ogc:def:crs:EPSG::4235

schemaName = GABRIEL

tableName = RUNWAYASSIGNMENT

pKeyCol = ID

pSpatialCol = LOCATION

sml31 = true


schemaLocation = $PATH/
tfdmRunwayAssignment
.xsd

featureMemberNS =
http://www.opengis.net/gmls.neB