Revision 6844
Added by Matt Jones almost 13 years ago
| docs/dev/metacat/source/submitting.rst | ||
|---|---|---|
| 792 | 792 |
Using the EarthGrid API (aka EcoGrid) |
| 793 | 793 |
------------------------------------- |
| 794 | 794 |
|
| 795 |
.. Note:: |
|
| 796 |
|
|
| 797 |
The EarthGrid/EcoGrid web service API is *deprecated* and will be removed from |
|
| 798 |
a future version of Metacat. Its functionality is being replaced by the |
|
| 799 |
standardized DataONE REST service interface. |
|
| 800 |
|
|
| 801 |
The EarthGrid (aka EcoGrid) provides access to disparate data on different |
|
| 802 |
networks (e.g., KNB, GBIF, GEON) and storage systems (e.g., Metacat and SRB), |
|
| 803 |
allowing scientists access to a wide variety of data and analytic resources |
|
| 804 |
(e.g., data, metadata, analytic workflows and processors) networked at different |
|
| 805 |
sites and at different organizations via the internet. |
|
| 806 |
|
|
| 807 |
Because Metacat supports the EarthGrid API (see table), it can query the |
|
| 808 |
distributed EarthGrid, retrieve metadata and data results, and write new and |
|
| 809 |
updated metadata and data back to the grid nodes. |
|
| 810 |
|
|
| 811 |
For more information about each EarthGrid service and its WSDL file, navigate |
|
| 812 |
to the "services" page on your Metacat server |
|
| 813 |
(e.g., http://knb.ecoinformatics.org/knb/services). |
|
| 814 |
Note that the AdminService and Version service that appear on this page are |
|
| 815 |
not part of EarthGrid. |
|
| 816 |
|
|
| 817 |
EarthGrid/EcoGrid API Summary |
|
| 818 |
|
|
| 819 |
+----------------------------+-----------------------------------------------------------------------------------------------------+ |
|
| 820 |
| Service | Description | |
|
| 821 |
+----------------------------+-----------------------------------------------------------------------------------------------------+ |
|
| 822 |
| AuthenticationQueryService | Search for and retrieve protected metadata and data from the EarthGrid as an authenticated user. | |
|
| 823 |
| | | |
|
| 824 |
| | Methods: ``query``, ``get`` | |
|
| 825 |
+----------------------------+-----------------------------------------------------------------------------------------------------+ |
|
| 826 |
| AuthenticationService | Log in and out of the EarthGrid | |
|
| 827 |
| | | |
|
| 828 |
| | Methods: ``login``, ``logout`` | |
|
| 829 |
+----------------------------+-----------------------------------------------------------------------------------------------------+ |
|
| 830 |
| IdentifierService | List, lookup, validate, and add Life Science Identifiers (LSIDs) to the EarthGrid | |
|
| 831 |
| | | |
|
| 832 |
| | Methods: ``isRegistered``, ``addLSID``, ``getNextRevision``, ``getNextObject``, ``getAllIds`` | |
|
| 833 |
+----------------------------+-----------------------------------------------------------------------------------------------------+ |
|
| 834 |
| PutService | Write metadata to the EarthGrid | |
|
| 835 |
| | | |
|
| 836 |
| | Methods: ``put`` | |
|
| 837 |
+----------------------------+-----------------------------------------------------------------------------------------------------+ |
|
| 838 |
| QueryService | Search for and retrieve metadata from the EarthGrid | |
|
| 839 |
| | | |
|
| 840 |
| | Methods: ``query``, ``get`` | |
|
| 841 |
+----------------------------+-----------------------------------------------------------------------------------------------------+ |
|
| 842 |
| RegistryService | Add, update, remove, and search for registered EarthGrid services. | |
|
| 843 |
| | Note: The WSDL for this service is found under http://ecogrid.ecoinformatics.org/registry/services | |
|
| 844 |
| | | |
|
| 845 |
| | Methods: ``add``, ``update``, ``remove``, ``list``, ``query`` | |
|
| 846 |
+----------------------------+-----------------------------------------------------------------------------------------------------+ |
|
| 847 |
|
|
| 795 | 848 |
Using Morpho |
| 796 | 849 |
------------ |
| 850 |
Morpho is a desktop tool created to facilitate the creation, storage, and |
|
| 851 |
retrieval of metadata. Morpho interfaces with any Metacat server, allowing |
|
| 852 |
users to upload, download, store, query and view relevant metadata and data |
|
| 853 |
using the network. Users can authorize the public or only selected colleagues |
|
| 854 |
to view their data files. |
|
| 797 | 855 |
|
| 856 |
Morpho is part of the Knowledge Network for Biocomplexity (KNB), a national |
|
| 857 |
network intended to facilitate ecological and environmental research on |
|
| 858 |
biocomplexity. To use Morpho with your Metacat, set the Metacat URL in the |
|
| 859 |
Morpho Preferences to point to your Metacat server. |
|
| 860 |
|
|
| 861 |
.. figure:: images/screenshots/image049.png |
|
| 862 |
:align: center |
|
| 863 |
|
|
| 864 |
Set the Metacat URL in the Morpho preferences to point to your Metacat. |
|
| 865 |
|
|
| 866 |
For more information about Morpho, please see: http://knb.ecoinformatics.org/morphoportal.jsp |
|
| 867 |
|
|
| 798 | 868 |
Creating Your Own Client |
| 799 | 869 |
------------------------ |
| 870 |
Metacat's client API is available in Java and Perl (the Java interface is |
|
| 871 |
described in this section and further detailed in the appendix). Some of the |
|
| 872 |
API is also available in Python and Ruby. The API allows client applications |
|
| 873 |
to easily authenticate users and perform basic Metacat operations such as |
|
| 874 |
reading metadata and data files; inserting, updating, and deleting files; and |
|
| 875 |
searching for packages based on metadata matches. |
|
| 800 | 876 |
|
| 877 |
The Client API is defined by the interface edu.ucsb.nceas.metacat.client.Metacat, |
|
| 878 |
and all operations are fully defined in the javadoc_ documentation. To use the |
|
| 879 |
client API, include the ``metacat-client.jar``, ``utilities.jar``, and |
|
| 880 |
``httpclient.jar`` in your classpath. After including these classes, you can |
|
| 881 |
begin using the API methods (see the next table). |
|
| 882 |
|
|
| 883 |
.. _javadoc: http://knb.ecoinformatics.org/software/metacat/dev/api/index.html |
|
| 884 |
|
|
| 885 |
The following code block displays a typical session for reading a document |
|
| 886 |
from Metacat using the Java client API. |
|
| 887 |
|
|
| 888 |
:: |
|
| 889 |
|
|
| 890 |
String metacatUrl = "http://foo.com/context/metacat"; |
|
| 891 |
String username = "uid=jones,o=NCEAS,dc=ecoinformatics,dc=org"; |
|
| 892 |
String password = "neverHarcodeAPasswordInCode"; |
|
| 893 |
try {
|
|
| 894 |
Metacat m = MetacatFactory.createMetacatConnection(metacatUrl); |
|
| 895 |
m.login(username, password); |
|
| 896 |
Reader r = m.read("testdocument.1.1");
|
|
| 897 |
// Do whatever you want with Reader r |
|
| 898 |
} catch (MetacatAuthException mae) {
|
|
| 899 |
handleError("Authorization failed:\n" + mae.getMessage());
|
|
| 900 |
} catch (MetacatInaccessibleException mie) {
|
|
| 901 |
handleError("Metacat Inaccessible:\n" + mie.getMessage());
|
|
| 902 |
} catch (Exception e) {
|
|
| 903 |
handleError("General exception:\n" + e.getMessage());
|
|
| 904 |
} |
|
| 905 |
|
|
| 906 |
Operations provided by Client API (Metacat.java class) |
|
| 907 |
|
|
| 908 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 909 |
| Method | Parameters and Throws | Description | |
|
| 910 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 911 |
| delete | ``public String delete(String docid) throws InsufficientKarmaException, MetacatException, MetacatInaccessibleException;`` | Delete an XML document in the repository. | |
|
| 912 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 913 |
| getAllDocids | ``public Vector getAllDocids(String scope) throws MetacatException;`` | Return a list of all docids that match a given scope. If scope is null, return all docids registered in the system. | |
|
| 914 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 915 |
| getLastDocid | ``public String getLastDocid(String scope) throws MetacatException;`` | Return the highest document ID for a given scope. Used by clients to determine the next free identifier in a sequence for a given scope. | |
|
| 916 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 917 |
| getloggedinuserinfo | ``public String getloggedinuserinfo() throws MetacatInaccessibleException;`` | Return the logged in user for this session. | |
|
| 918 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 919 |
| getNewestDocRevision | ``public int getNewestDocRevision(String docId) throws MetacatException;`` | Return the latest revision of specified the document from Metacat | |
|
| 920 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 921 |
| getSessonId | ``public String getSessionId();`` | Return the session identifier for this session. | |
|
| 922 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 923 |
| insert | ``public String insert(String docid, Reader xmlDocument, Reader schema) throws InsufficientKarmaException, MetacatException, IOException, MetacatInaccessibleException;`` | Insert an XML document into the repository. | |
|
| 924 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 925 |
| isRegistered | ``public boolean isRegistered(String docid) throws MetacatException;`` | Return true if given docid is registered; false if not. | |
|
| 926 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 927 |
| login | ``public String login(String username, String password) throws MetacatAuthException, MetacatInaccessibleException;`` | Log in to a Metacat server. | |
|
| 928 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 929 |
| logout | ``public String logout() throws MetacatInaccessibleException, MetacatException;`` | Log out of a Metacat server. | |
|
| 930 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 931 |
| query | ``public Reader query(Reader xmlQuery) throws MetacatInaccessibleException, IOException;`` | Query the Metacat repository and return the result set as a Reader. | |
|
| 932 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 933 |
| query | ``public Reader query(Reader xmlQuery, String qformat) throws MetacatInaccessibleException, IOException;`` | Query the Metacat repository with the given metacat-compatible query format and return the result set as a Reader. | |
|
| 934 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 935 |
| read | ``public Reader read(String docid) throws InsufficientKarmaException, MetacatInaccessibleException, DocumentNotFoundException, MetacatException;`` | Read an XML document from the Metacat server. | |
|
| 936 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 937 |
| readInlineData | ``public Reader readInlineData(String inlinedataid) throws InsufficientKarmaException, MetacatInaccessibleException, MetacatException;`` | Read inline data from the Metacat server session. | |
|
| 938 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 939 |
| setAccess | ``public String setAccess(String _docid, String _principal, String _permission, String _permType, String _permOrder ); throws InsufficientKarmaException, MetacatException, MetacatInaccessibleException;`` | Set permissions for an XML document in the Metacat repository. | |
|
| 940 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 941 |
| setMetacatUrl | ``public void setMetacatUrl(String metacatUrl);`` | Set the MetacatUrl to which connections should be made. | |
|
| 942 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 943 |
| setSessionId | ``public void setSessionId(String sessionId);`` | Set the session identifier for this session. | |
|
| 944 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 945 |
| update | ``public String update(String docid, Reader xmlDocument, Reader schema) throws InsufficientKarmaException, MetacatException, IOException, MetacatInaccessibleException;`` | Update an XML document in the repository by providing a new version of the XML document. | |
|
| 946 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 947 |
| upload | ``public String upload(String docid, File file) throws InsufficientKarmaException, MetacatException, IOException, MetacatInaccessibleException;`` | Upload a data document into the repository. | |
|
| 948 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 949 |
| upload | ``public String publicupload(String docid, String fileName, InputStream fileData, int size) throws InsufficientKarmaException, MetacatException, IOException, MetacatInaccessibleException;`` | Upload a data document into the repository. | |
|
| 950 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
| 951 |
|
|
| docs/dev/metacat/source/geoserver.rst | ||
|---|---|---|
| 1 | 1 |
Metacat's Use of Geoserver |
| 2 | 2 |
========================== |
| 3 | 3 |
|
| 4 |
Under construction! |
|
| 4 |
GeoServer 1.4.0, an open source Web Mapping Service (WMS) written in Java, is |
|
| 5 |
bundled with Metacat and can be used to render spatial data as web-deliverable |
|
| 6 |
maps (see figure). Metacat uses Community MapBuilder (a pure HTML and JavaScript |
|
| 7 |
application that uses AJAX and XSLT) to provide a web-based user interface for |
|
| 8 |
interacting with the generated maps. You can use any WMS-compatible client |
|
| 9 |
(e.g., ArcGIS, QGIS, JUMP, UDig, OpenLayers, Mapbender, Map Builder). Please |
|
| 10 |
note the mapping functionality is only supported for Metacat servlets running |
|
| 11 |
under Tomcat 6 or later. |
|
| 5 | 12 |
|
| 6 |
Heading 1 |
|
| 7 |
------------ |
|
| 13 |
IMPORTANT: Regardless of whether you plan on using the mapping functionality |
|
| 14 |
you should, for security purposes, configure GeoServer so that it doesn't |
|
| 15 |
use the default password. For instructions, please see |
|
| 16 |
Geoserver Password Configuration. |
|
| 8 | 17 |
|
| 9 |
Heading 2 |
|
| 10 |
------------ |
|
| 18 |
.. figure:: images/screenshots/image051.jpg |
|
| 19 |
:align: center |
|
| 20 |
|
|
| 21 |
A map generated by Metacat's GeoServer. Points and "bounding boxes" |
|
| 22 |
represent the geographic extent of datasets stored in the KNB Metacat repository. |
|
| 11 | 23 |
|
| 24 |
GeoServer supports a wide variety of vector GIS data sources, which can be |
|
| 25 |
styled using Styled Layer Descriptors (SLDs) and output as images (the default) |
|
| 26 |
or raw vector data (GML or KML). |
|
| 27 |
|
|
| 28 |
Currently, GeoServer can be used with the following limitations: |
|
| 29 |
|
|
| 30 |
* The GeoServer will only map documents that are publicly available. This is |
|
| 31 |
because the mapping server's support for permissions control is not as |
|
| 32 |
fine-grained as Metacat's. |
|
| 33 |
* The GeoServer can only access documents that conform to one chosen schema. |
|
| 34 |
This is because only one set of xpaths can be defined in the Metacat properties. |
|
| 35 |
* GeoServer 1.4, the version bundled with Metacat, does not support raster |
|
| 36 |
input (e.g., satellite imagery or digital elevation models). We suggest |
|
| 37 |
setting up UMN Mapserver if you aim to serve raster data. |
|
| 38 |
|
|
| 39 |
Metacat developers plan to continue extending and improving Metacat's mapping |
|
| 40 |
capabilities. If you are interested in contributing to those efforts, or if |
|
| 41 |
you are interested in learning more about the architecture and future plans for |
|
| 42 |
the mapping software. |
|
| 43 |
|
|
| 44 |
Installing and Configuring |
|
| 45 |
-------------------------- |
|
| 46 |
Metacat's GeoServer is automatically installed when Metacat is installed. If |
|
| 47 |
you do NOT wish to run GeoServer, set the runSpatialOption property in the |
|
| 48 |
``metacat.properties`` file (found in the source code's lib directory) to |
|
| 49 |
false before building and deploying Metacat. |
|
| 50 |
|
|
| 51 |
The GeoServer bundled with Metacat comes with a world-countries base layer |
|
| 52 |
and a default configuration that is already aware of Metacat's spatial cache. |
|
| 53 |
To further configure GeoServer, use its Web-based configuration utility, |
|
| 54 |
which is available at: http://your.server.com/context/geoserver.jsp |
|
| 55 |
(e.g., http://knb.ecoinformatics.org/knb/geoserver.jsp). |
|
| 56 |
|
|
| 57 |
Common configuration tasks include: |
|
| 58 |
|
|
| 59 |
* Adding a Map to a Web Page or Skin |
|
| 60 |
* Configuring the Size and Initial Extent of the Map |
|
| 61 |
* Configuring the Layout of the HTML Mapping Interface |
|
| 62 |
* Changing the Lat/Long Display to Degree-Minutes-Seconds |
|
| 63 |
* Configuring the "Select Location Drop-down Menu |
|
| 64 |
* Configuring the Visual Portrayal of Geospatial Data (e.g., symbology and color) |
|
| 65 |
* Adding Other Spatial Datasets to the Web Map |
|
| 66 |
|
|
| 67 |
.. figure:: images/screenshots/image053.jpg |
|
| 68 |
:align: center |
|
| 69 |
|
|
| 70 |
GeoServer's Web-based administrative interface. |
|
| 71 |
|
|
| 72 |
Note: Some configurations may need to be made to the XML files as well. |
|
| 73 |
|
|
| 74 |
Community Mabuilder, which Metacat uses as the front-end for GeoServer's WMS |
|
| 75 |
service, provides interface components or "widgets" (e.g., the map, a box zoom, |
|
| 76 |
layer list, "Select Location" drop-down menu, scale bar, lat/long coordinates, |
|
| 77 |
and a query form) that make it easy to deploy highly-functional Web mapping |
|
| 78 |
applications with minimal coding. The WMS layers are configured through a Web |
|
| 79 |
Map Context (WMC) document. This context document can be edited to customize |
|
| 80 |
the initial extent of the map, the ordering and visibility of layers and, of |
|
| 81 |
course, the source and name of the WMS layer. |
|
| 82 |
|
|
| 83 |
Mapbuilder has three main configuration files used to customize the map |
|
| 84 |
interface (Table 5.1). If you plan to customize the map interface, you must |
|
| 85 |
use a source code distribution of Metacat. Default configurations are in:: |
|
| 86 |
|
|
| 87 |
$METACAT/lib/style/common/spatial_templates/spatial1/ |
|
| 88 |
|
|
| 89 |
+--------------------------------+-------------+---------------------------------------------------------------------+ |
|
| 90 |
| Document | Location | Description | |
|
| 91 |
+--------------------------------+-------------+---------------------------------------------------------------------+ |
|
| 92 |
| Web map context document (WMC) | context.xml | The WMC is used to customize the initial extent of the map, | |
|
| 93 |
| | | the order of the map layers, and the source and name of each layer. | |
|
| 94 |
+--------------------------------+-------------+---------------------------------------------------------------------+ |
|
| 95 |
| Mapbuilder configuration file | context.xml | Defines the Mapbuilder widgets and their behavior | |
|
| 96 |
+--------------------------------+-------------+---------------------------------------------------------------------+ |
|
| 97 |
| The Map file | map.html | Loads the Mapbuilder JavaScript library and controls the | |
|
| 98 |
| | | HTML layout of the widgets. | |
|
| 99 |
+--------------------------------+-------------+---------------------------------------------------------------------+ |
|
| 100 |
|
|
| 101 |
NOTE: By default, the first time Metacat is restarted, it generates a |
|
| 102 |
"spatial cache" containing geographic information about documents in its |
|
| 103 |
repository. This default behavior is specified in lib/metacat.properties, |
|
| 104 |
where the regenerateCacheOnRestart parameter is set to true. The information |
|
| 105 |
in the spatial cache is stored in a GIS-compatible format (the ESRI Shapefile) |
|
| 106 |
and consists of the document name and its geographic coverage. When documents |
|
| 107 |
are inserted, deleted, and updated in the Metacat repository, Metacat |
|
| 108 |
automatically syncs the spatial cache to reflect the changes. Because |
|
| 109 |
generating the cache can take a considerable amount of time (several minutes |
|
| 110 |
in the case of a few thousand documents), Metacat resets the |
|
| 111 |
regenerateCacheOnRestart property to false after the spatial cache has been |
|
| 112 |
generated. Note that if you upgrade or reinstall Metacat, the spatial cache |
|
| 113 |
will be regenerated again. |
|
| 114 |
|
|
| 115 |
Adding a Map to a Web Page or Skin |
|
| 116 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
| 117 |
To add a map to a Web page, simply include the map interface using an iframe:: |
|
| 118 |
|
|
| 119 |
<iframe scrolling="no" frameborder="0" width="736" height="520" |
|
| 120 |
src="/knb/style/common/spatial_templates/spatial1/map.html"> |
|
| 121 |
</iframe> |
|
| 122 |
|
|
| 123 |
The map URL, ``/knb/style/common/spatial_templates/spatial1/map.html``, is |
|
| 124 |
the default map interface. If you plan to customize the map interface, copy |
|
| 125 |
the spatial1 directory into your skin's directory (either the default or |
|
| 126 |
customized skin directory). |
|
| 127 |
|
|
| 128 |
:: |
|
| 129 |
|
|
| 130 |
cp -r style/common/spatial_templates/spatial1 /style/skins/<myskin>/spatial |
|
| 131 |
|
|
| 132 |
You can access the customized map with the URL: ``/knb/style/skins/<myskin>/spatial/map.html`` |
|
| 133 |
|
|
| 134 |
Configuring the Size and Initial Extent of the Map |
|
| 135 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
| 136 |
Before you configure the size and initial extent of the map, make sure that you |
|
| 137 |
have copied the default spatial settings into your skin's directory (see :doc:`configuration`). |
|
| 138 |
Once the settings have been copied, you can modify the map's initial extent in |
|
| 139 |
the context settings: ``${skin.dir}/spatial/context.xml``.
|
|
| 140 |
|
|
| 141 |
To change the map size and/or initial extent, edit the following lines:: |
|
| 142 |
|
|
| 143 |
<Window width="720" height="360" /> |
|
| 144 |
<BoundingBox SRS="EPSG:4326" minx="-180" miny="-90" maxx="180" maxy="90" /> |
|
| 145 |
|
|
| 146 |
Where ``width`` and ``height`` specify the map size in pixels, ``minx/maxx`` |
|
| 147 |
represent the range of longitudes and ``miny/maxy`` represent the range of latitudes. |
|
| 148 |
|
|
| 149 |
Configuring the Layout of the HTML Mapping Interface |
|
| 150 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
| 151 |
Before you configure the size and initial extent of the map, make sure that |
|
| 152 |
you have copied the default spatial settings into your skin's directory. |
|
| 153 |
Once the settings have been copied, you can modify the layout here: |
|
| 154 |
``${skin.dir}/spatial/map.html``.
|
|
| 155 |
|
|
| 156 |
``Map.html`` is a simple HTML file with a tabular layout. Map components are |
|
| 157 |
abstracted into "widgets", blocks with a specific id (e.g., locationsSelect |
|
| 158 |
and mainButtonBar), which can be reorganized within the table. |
|
| 159 |
To customize the map extent and appearance, modify the Web map context |
|
| 160 |
document (``context.xml``) and/or Mapbuilder's configuration file (``config.xml``). |
|
| 161 |
Both files are in the spatial directory inside the skins folder. |
|
| 162 |
|
|
| 163 |
Changing the Lat/Long Display to Degree-Minutes-Seconds |
|
| 164 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
| 165 |
By default, the map display shows the cursor's position in decimal degrees |
|
| 166 |
(the preferred format for many GPS/GIS applications). To report coordinates as |
|
| 167 |
degrees minutes-seconds, edit the spatial configuration file: |
|
| 168 |
|
|
| 169 |
1. If you have not already copied the default spatial settings into your skin's |
|
| 170 |
directory, do so now |
|
| 171 |
2. Open the ${skin.dir}/spatial/config.xml file.
|
|
| 172 |
3. Edit the CursorTrack widget so that the content is the following: |
|
| 173 |
|
|
| 174 |
:: |
|
| 175 |
|
|
| 176 |
<CursorTrack id="cursorTrack"> |
|
| 177 |
<mouseHandler>mainMap</mouseHandler> |
|
| 178 |
<showDMS>true</showDMS> |
|
| 179 |
<showLatLong>true</showLatLong> |
|
| 180 |
</CursorTrack> |
|
| 181 |
|
|
| 182 |
4. Save and close the configuration file. |
|
| 183 |
|
|
| 184 |
Configuring the "Select Location" Drop-down Menu |
|
| 185 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
| 186 |
Before you configure the menu items, make sure that you have copied the default |
|
| 187 |
spatial settings into your skin's directory. |
|
| 188 |
|
|
| 189 |
The locations that appear in the "Select Location" drop-down menu are specified |
|
| 190 |
in the ``${skin.dir}/spatial/named_locations.xml`` file. Each location is
|
|
| 191 |
defined as a ``gml:featureMember``. Edit the featureMember's ``gml:name`` and |
|
| 192 |
``gml:coordinates`` fields to edit or add new locations. |
|
| 193 |
|
|
| 194 |
:: |
|
| 195 |
|
|
| 196 |
<gml:featureMember> |
|
| 197 |
<locationDef> |
|
| 198 |
<gml:name>ACM Wilderness Field Station</gml:name> |
|
| 199 |
<spatialKeyword> |
|
| 200 |
<gml:location> |
|
| 201 |
<gml:Envelope srsName="http://www.opengis.net/gml/srs/epsg.xml#4326"> |
|
| 202 |
<gml:coordinates>-91.956,47.87 -91.706,48.12</gml:coordinates> |
|
| 203 |
</gml:Envelope> |
|
| 204 |
</gml:location> |
|
| 205 |
</spatialKeyword> |
|
| 206 |
</locationDef> |
|
| 207 |
</gml:featureMember> |
|
| 208 |
|
|
| 209 |
Configuring the Visual Portrayal of Geospatial Data (e.g., symbology and color) |
|
| 210 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
| 211 |
Geospatial data sets are styled through the use of Styled Layer Descriptors |
|
| 212 |
(SLD). The default SLDs used for the data points and data bounding boxes are in |
|
| 213 |
``/lib/spatial/geoserver/data/styles/`` and are named data_points_style.sld and |
|
| 214 |
data_bounds_style.sld, respectively. |
|
| 215 |
|
|
| 216 |
You can find a more detailed tutorial on using SLD with GeoServer at:: |
|
| 217 |
|
|
| 218 |
http://geoserver.org/display/GEOSDOC/SLD+Intro+Tutorial. |
|
| 219 |
|
|
| 220 |
Adding Other Spatial Datasets to the Web Map |
|
| 221 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
| 222 |
If you have vector GIS data sets, such as weather or topographical information, |
|
| 223 |
on your server that you'd like to include in the interactive map, you must |
|
| 224 |
first register the data set with GeoServer. After the data set has been |
|
| 225 |
registered, you can add the layer to the map. You can also add spatial layers |
|
| 226 |
that have been made publically available through WMS (There are hundreds of |
|
| 227 |
spatial data sets available. Check out wms-sites.com for good catalog). |
|
| 228 |
Instructions for adding publically available layers are included at the end |
|
| 229 |
of this section. |
|
| 230 |
|
|
| 231 |
To register the data set and add it to the map: |
|
| 232 |
|
|
| 233 |
1. Point your browser to http://your.server/context/geoserver.jsp, log in to |
|
| 234 |
GeoServer, and navigate to the "Data Stores" configuration page |
|
| 235 |
under Config > Data > Stores. |
|
| 236 |
2. Create a new Shapefile and assign it a DataStore ID. The DataStore ID can |
|
| 237 |
contain letters and numbers. It is just used internally, and should be |
|
| 238 |
unique. Click New. |
|
| 239 |
|
|
| 240 |
.. figure:: images/screenshots/image055.jpg |
|
| 241 |
:align: center |
|
| 242 |
|
|
| 243 |
Creating a new shapefile using GeoServers web-based administrative interface. |
|
| 244 |
|
|
| 245 |
3. On the next screen, select the "metacat" namespace from the drop-down menu |
|
| 246 |
and point to the GIS data file on the file system, relative to: |
|
| 247 |
|
|
| 248 |
:: |
|
| 249 |
|
|
| 250 |
{tomcat.dir}/webapps/{context}/
|
|
| 251 |
|
|
| 252 |
The Description, if specified, is mostly used internally to provide other |
|
| 253 |
administrators with information about the DataStore. Click Submit. |
|
| 254 |
|
|
| 255 |
4. Navigate to the "Feature Type" configuration page under |
|
| 256 |
Config > Data > Feature Type. Select your new data store from the |
|
| 257 |
drop-down menu. Click New. |
|
| 258 |
5. Style the layer using a style from the drop-down style menu, or click |
|
| 259 |
"Create new SLD" to create a new Style object and corresponding SLD |
|
| 260 |
(this option provides more control over the style). You should also define a |
|
| 261 |
spatial reference system (SRS) number for the new layer. |
|
| 262 |
Most lat/long data is "4326". If your data is in another projection, |
|
| 263 |
determine its spatial reference system using the help links provided. |
|
| 264 |
|
|
| 265 |
.. figure:: images/screenshots/image057.jpg |
|
| 266 |
:align: center |
|
| 267 |
|
|
| 268 |
GeoServer's FeatureType Editor. The Style and SRS settings discussed in step 5 are highlighted. |
|
| 269 |
|
|
| 270 |
6. Click "Apply" and "Save" |
|
| 271 |
7. Try out the styled data set as a WMS layer using a URL like: |
|
| 272 |
|
|
| 273 |
:: |
|
| 274 |
|
|
| 275 |
http://your.server/context/wms?VERSION=1.1.1&REQUEST=GetMap&SERVICE=WMS&LAYERS=metacat:newLayer&SRS=EPSG:4326&BBOX=-180,-90,180,90&WIDTH=720&HEIGHT=360&FORMAT=image/gif&STYLES=&TRANSPARENT=TRUE&UNIQUEID= |
|
| 276 |
|
|
| 277 |
Where your.server/context is the name of your server and context (e.g., |
|
| 278 |
http://knb.ecoinformatics.org/knb) and newLayer is the name of the new layer. |
|
| 279 |
The other parameters control which part of the layer is displayed. |
|
| 280 |
|
|
| 281 |
If data is properly displayed, add the map to your map context document (Step 8). |
|
| 282 |
|
|
| 283 |
8. Locate the Web map context document (usually {skin}/spatial/context.xml) and
|
|
| 284 |
open the file in a text editor. |
|
| 285 |
9. Locate the Layer entry for an existing layer next to which you wish to stack |
|
| 286 |
your layer (the first layers in the context are rendered at the bottom). |
|
| 287 |
|
|
| 288 |
10. Create a new Layer entry, by copying and pasting the existing entry for the |
|
| 289 |
metacat data_points layer and editing the Layer Name and Title. The title |
|
| 290 |
is displayed in the map legend. Note: if you'd like to use transparency, |
|
| 291 |
leave the image format set to image/gif (IE pre-7 has trouble with PNG |
|
| 292 |
transparency). |
|
| 293 |
|
|
| 294 |
:: |
|
| 295 |
|
|
| 296 |
<Layer queryable="0" hidden="0"> |
|
| 297 |
<Server service="OGC:WMS" version="1.1.1" |
|
| 298 |
title="DatasetPoints"> |
|
| 299 |
<OnlineResource xlink:type="simple" xlink:href="../../../../wms" /> |
|
| 300 |
</Server> |
|
| 301 |
<Name>metacat:data_points</Name> |
|
| 302 |
<Title>Dataset Points</Title> |
|
| 303 |
<SRS>EPSG:4326</SRS> |
|
| 304 |
<FormatList> |
|
| 305 |
<Format current="1">image/gif</Format> |
|
| 306 |
</FormatList> |
|
| 307 |
</Layer> |
|
| 308 |
|
|
| 309 |
11. Point your browser to the map interface. Your new layer should appear with |
|
| 310 |
the existing ones. |
|
| 311 |
|
|
| 312 |
Adding External Spatial Data Made Publically Available through WMS |
|
| 313 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
| 314 |
There are hundreds of sources of spatial data made publically available |
|
| 315 |
through WMS. (check out http://wms-sites.com for good catalog). To add these |
|
| 316 |
data sources to your map, locate your skin's context file |
|
| 317 |
(``${skin.dir}/spatial/context.xml``) and add a new Layer by copying and
|
|
| 318 |
pasting an existing Layer and modifying as appropriate: modify the |
|
| 319 |
OnlineResourceURL, Name, Title and Style to match the WMS layer you'd like to |
|
| 320 |
use. See the mapbuilder Add WMS Tutorial for further details. |
|
| 321 |
|
|
| 322 |
Spatial Queries |
|
| 323 |
--------------- |
|
| 324 |
To find out which documents in the Metacat repository lie in a specified |
|
| 325 |
geographic region, query the spatial cache using Metacat's spatial_query action. |
|
| 326 |
Metacat can perform any query supported by the WFS/WMS standards. |
|
| 327 |
|
|
| 328 |
An example of a spatial query string is:: |
|
| 329 |
|
|
| 330 |
http://localhost/knb/metacat?action=spatial_query&xmin=-117.5&xmax=-64&ymin=3&ymax=46&skin=default |
|
| 331 |
|
|
| 332 |
Where ``xmin``, ``xmax``, ``ymin`` and ``ymax`` represent the western, eastern, |
|
| 333 |
southern and northern bounding coordinates (the "bounding box"), respectively. |
|
| 334 |
The spatial query action returns all documents that overlap or that are |
|
| 335 |
contained inside the specified spatial coordinates. The result set is returned |
|
| 336 |
as HTML using the style of the specified skin (in this example, default). |
|
| 337 |
|
|
Also available in: Unified diff
Completed 'Submission' page conversion, and also converted GeoServer docs to
RST format.