"Fossies" - the Fresh Open Source Software Archive

Member "geoserver-2.18.1/user/data/app-schema/app-schema-resolution.html" (19 Nov 2020, 14956 Bytes) of package /linux/www/geoserver-2.18.1-htmldoc.zip:


The requested HTML page contains a <FORM> tag that is unusable on "Fossies" in "automatic" (rendered) mode so that page is shown as HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    2   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US">
    4 <head>
    5   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    6   
    7   <title>Application Schema Resolution &mdash; GeoServer 2.18.1 User Manual</title>
    8   <link rel="stylesheet" href="../../_static/blueprint/screen.css" type="text/css" media="screen, projection" />
    9   <link rel="stylesheet" href="../../_static/blueprint/print.css" type="text/css" media="print" /> 
   10   <!--[if IE]>
   11   <link rel="stylesheet" href="../../_static/blueprint/ie.css" type="text/css" media="screen, projection" />
   12   <![endif]-->
   13   <link rel="stylesheet" href="../../_static/default.css" type="text/css" />
   14   <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
   15   <script type="text/javascript">
   16     var DOCUMENTATION_OPTIONS = {
   17         URL_ROOT:    '../../',
   18         VERSION:     '2.18.1',
   19         COLLAPSE_MODINDEX: false,
   20         FILE_SUFFIX: '.html'
   21     };
   22   </script>
   23   <script type="text/javascript" src="../../_static/jquery.js"></script>
   24   <script type="text/javascript" src="../../_static/doctools.js"></script>
   25   <script type="text/javascript" src="../../_static/searchtools.js"></script>
   26   <script type="text/javascript" src="../../searchindex.js"></script>
   27   <link rel="shortcut icon" href="../../_static/geoserver.ico"/>
   28       <link rel="search" title="Search" href="../../search.html" />
   29       <link rel="top" title="GeoServer 2.18.1 User Manual" href="../../index.html" />
   30       <link rel="up" title="Application schemas" href="index.html" />
   31       <link rel="next" title="Supported GML Versions" href="supported-gml-versions.html" />
   32       <link rel="prev" title="Mapping File" href="mapping-file.html" />
   33 </head>
   34 <body class="data/app-schema/app-schema-resolution">
   35   <div id="header" class="selfclear">
   36     <div class="wrap selfclear">
   37       <div id="logo"><a href="../../index.html">GeoServer 2.18.1 User Manual</a></div>
   38       <ul id="top-nav">
   39         <li class="first"><a href="http://geoserver.org/about">About</a></li>
   40         <li><a href="http://blog.geoserver.org/">Blog</a></li>
   41         <li><a href="http://geoserver.org/download">Download</a></li>
   42         <!--<li><a href="../../index.html">Documentation</a></li>-->
   43       </ul>
   44         <form id="quick-search" action="../../search.html" method="get">
   45           <fieldset>
   46             <input type="hidden" name="check_keywords" value="yes" />
   47             <input type="hidden" name="area" value="default" />
   48             <input id="quick-search-query" type="text" name="q" accessKey="q" name="searchQuery.queryString" size="25" value="Search Documentation&hellip;" size="20" tabindex="3" onblur="if(this.value=='') this.value='Search Documentation&hellip;';" onfocus="if(this.value=='Search Documentation&hellip;') this.value='';" />
   49             <input id="quick-search-submit" type="image" value="Search" src="../../_static/chrome/search_icon_green.png" />
   50           </fieldset>
   51         </form>
   52     </div><!-- /.wrap -->
   53   </div><!-- /#header -->
   54   <div id="main">
   55     <div class="wrap selfclear">
   56       <div id="content-left" class="content-border"></div>
   57       <div id="content">
   58 <ul id="breadcrumbs">
   59   
   60   <li><a href="../../index.html">GeoServer 2.18.1 User Manual</a> &raquo;</li>
   61   <li><a href="../index.html" accesskey="U">Data management</a> &raquo;</li>
   62   <li><a href="index.html" accesskey="U">Application schemas</a> &raquo;</li>
   63   <li>Application Schema Resolution</li>
   64 </ul>
   65 <ul id="relatedlinks" class="selfclear">
   66   <li class="first">
   67     <a href="../../py-modindex.html" title="Python Module Index"
   68        accesskey="">modules</a></li>
   69   <li>
   70     <a href="supported-gml-versions.html" title="Supported GML Versions"
   71        accesskey="N">next</a>|</li>
   72   <li>
   73     <a href="mapping-file.html" title="Mapping File"
   74        accesskey="P">previous</a>|</li>
   75 </ul>
   76         
   77   <div class="section" id="application-schema-resolution">
   78 <span id="app-schema-app-schema-resolution"></span><h1>Application Schema Resolution<a class="headerlink" href="#application-schema-resolution" title="Permalink to this headline"></a></h1>
   79 <p>To be able to encode XML responses conforming to a GML application schema, the app-schema plugin must be able to locate the application schema files (XSDs) that define the schema. This page describes the schema resolution process.</p>
   80 <div class="section" id="schema-downloading-is-now-automatic-for-most-users">
   81 <h2>Schema downloading is now automatic for most users<a class="headerlink" href="#schema-downloading-is-now-automatic-for-most-users" title="Permalink to this headline"></a></h2>
   82 <p>GeoServer will automatically download and cache (see <a class="reference internal" href="#cache">Cache</a> below) all the schemas it needs the first time it starts if:</p>
   83 <ol class="arabic simple">
   84 <li><p>All the application schemas you use are accessed via http/https URLs, and</p></li>
   85 <li><p>Your GeoServer instance is deployed on a network that permits it to download them.</p></li>
   86 </ol>
   87 <div class="admonition note">
   88 <p class="admonition-title">Note</p>
   89 <p>This is the recommended way of using GeoServer app-schema for most users.</p>
   90 </div>
   91 <p>If cached downloading is used, no manual handling of schemas will be required. The rest of this page is for those with more complicated arrangements, or who wish to clear the cache.</p>
   92 </div>
   93 <div class="section" id="resolution-order">
   94 <h2>Resolution order<a class="headerlink" href="#resolution-order" title="Permalink to this headline"></a></h2>
   95 <p>The order of sources used to resolve application schemas is:</p>
   96 <ol class="arabic simple">
   97 <li><p><a class="reference internal" href="#oasis-catalog">OASIS Catalog</a></p></li>
   98 <li><p><a class="reference internal" href="#classpath">Classpath</a></p></li>
   99 <li><p><a class="reference internal" href="#cache">Cache</a></p></li>
  100 </ol>
  101 <p>Every attempt to load a schema works down this list, so imports can be resolved from sources other than that used for the originating document. For example, an application schema in the cache that references a schema found in the catalog will use the version in the catalog, rather than caching it. This allows users to supply unpublished or modified schemas sourced from, for example, the catalog, at the cost of interoperability (how do WFS clients get them?).</p>
  102 </div>
  103 <div class="section" id="oasis-catalog">
  104 <h2>OASIS Catalog<a class="headerlink" href="#oasis-catalog" title="Permalink to this headline"></a></h2>
  105 <p>An <a class="reference external" href="http://www.oasis-open.org/committees/entity/spec-2001-08-06.html">OASIS XML Catalog</a> is a standard configuration file format that instructs an XML processing system how to process entity references. The GeoServer app-schema resolver uses catalog URI semantics to locate application schemas, so <code class="docutils literal notranslate"><span class="pre">uri</span></code> or <code class="docutils literal notranslate"><span class="pre">rewriteURI</span></code> entries should be present in your catalog. The optional mapping file  <code class="docutils literal notranslate"><span class="pre">catalog</span></code> element provides the location of the OASIS XML Catalog configuration file, given as a path relative to the mapping file, for example:</p>
  106 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&lt;</span><span class="n">catalog</span><span class="o">&gt;../../../</span><span class="n">schemas</span><span class="o">/</span><span class="n">catalog</span><span class="o">.</span><span class="n">xml</span><span class="o">&lt;/</span><span class="n">catalog</span><span class="o">&gt;</span>
  107 </pre></div>
  108 </div>
  109 <p>Earlier versions of the app-schema plugin required all schemas to be present in the catalog. This is no longer the case. Because the catalog is searched first, existing catalog-based deployments will continue to work as before.</p>
  110 <p>To migrate an existing GeoServer app-schema deployment that uses an OASIS Catalog to instead use cached downloads (see <a class="reference internal" href="#cache">Cache</a> below), remove all <code class="docutils literal notranslate"><span class="pre">catalog</span></code> elements from your mapping files and restart GeoServer.</p>
  111 </div>
  112 <div class="section" id="classpath">
  113 <h2>Classpath<a class="headerlink" href="#classpath" title="Permalink to this headline"></a></h2>
  114 <p>Java applications such as GeoServer can load resources from the Java classpath. GeoServer app-schema uses a simple mapping from an http or https URL to a classpath resource location. For example, an application schema published at <code class="docutils literal notranslate"><span class="pre">http://schemas.example.org/exampleml/exml.xsd</span></code> would be found on the classpath if it was stored either:</p>
  115 <ul class="simple">
  116 <li><p>at <code class="docutils literal notranslate"><span class="pre">/org/example/schemas/exampleml/exml.xsd</span></code> in a JAR file on the classpath (for example, a JAR file in <code class="docutils literal notranslate"><span class="pre">WEB-INF/lib</span></code>) or,</p></li>
  117 <li><p>on the local filesystem at <code class="docutils literal notranslate"><span class="pre">WEB-INF/classes/org/example/schemas/exampleml/exml.xsd</span></code> .</p></li>
  118 </ul>
  119 <p>The ability to load schemas from the classpath is intended to support testing, but may be useful to users whose communities supply JAR files containing their application schemas.</p>
  120 </div>
  121 <div class="section" id="cache">
  122 <span id="app-schema-cache"></span><h2>Cache<a class="headerlink" href="#cache" title="Permalink to this headline"></a></h2>
  123 <p>If an application schema cannot be found in the catalog or on the classpath, it is downloaded from the network and stored in a subdirectory <code class="docutils literal notranslate"><span class="pre">app-schema-cache</span></code> of the GeoServer data directory.</p>
  124 <ul class="simple">
  125 <li><p>Once schemas are downloaded into the cache, they persist indefinitely, including over GeoServer restarts.</p></li>
  126 <li><p>No attempt will be made to retrieve new versions of cached schemas.</p></li>
  127 <li><p>To clear the cache, remove the  subdirectory <code class="docutils literal notranslate"><span class="pre">app-schema-cache</span></code> of the GeoServer data directory and restart GeoServer.</p></li>
  128 </ul>
  129 <p>GeoServer app-schema uses a simple mapping from an http or https URL to local filesystem path. For example, an application schema published at <code class="docutils literal notranslate"><span class="pre">http://schemas.example.org/exampleml/exml.xsd</span></code> would be downloaded and stored as <code class="docutils literal notranslate"><span class="pre">app-schema-cache/org/example/schemas/exampleml/exml.xsd</span></code> . Note that:</p>
  130 <ul class="simple">
  131 <li><p>Only <code class="docutils literal notranslate"><span class="pre">http</span></code> and <code class="docutils literal notranslate"><span class="pre">https</span></code> URLs are supported.</p></li>
  132 <li><p>Port numbers, queries, and fragments are ignored.</p></li>
  133 </ul>
  134 <p>If your GeoServer instance is deployed on a network whose firewall rules prevent outgoing TCP connections on port 80 (http) or 443 (https), schema downloading will not work. (For security reasons, some service networks [“demilitarised zones”] prohibit such outgoing connections.) If schema downloading is not permitted on your network, there are three solutions:</p>
  135 <ol class="arabic simple">
  136 <li><p>Either: Install and configure GeoServer on another network that can make outgoing TCP connections, start GeoServer to trigger schema download, and then manually copy the <code class="docutils literal notranslate"><span class="pre">app-schema-cache</span></code> directory to the production server. This is the easiest option because GeoServer automatically downloads all the schemas it needs, including dependencies.</p></li>
  137 <li><p>Or: Deploy JAR files containing all required schema files on the classpath (see <a class="reference internal" href="#classpath">Classpath</a> above).</p></li>
  138 <li><p>Or: Use a catalog (see <a class="reference internal" href="#oasis-catalog">OASIS Catalog</a> above).</p></li>
  139 </ol>
  140 <div class="admonition warning">
  141 <p class="admonition-title">Warning</p>
  142 <p>System property “schema.cache.dir” with a cache directory location is required for using a mapping file from a remote URL with ‘<a class="reference external" href="http://">http://</a>’ or ‘<a class="reference external" href="https://">https://</a>’ protocol.</p>
  143 </div>
  144 </div>
  145 </div>
  146 
  147 
  148       <div class="selfclear pagination-nav">
  149           <div class="leftwise"><strong>Previous</strong>: <a href="mapping-file.html" title="previous chapter">Mapping File</a></div>
  150           <div class="rightwise"><strong>Next</strong>: <a href="supported-gml-versions.html" title="next chapter">Supported GML Versions</a></div>
  151       </div>
  152       </div><!-- /#content> -->
  153       <div id="content-right" class="content-border"></div>
  154   <div id="sidebar" class="contrast">
  155       <div id="toc" class="section">
  156         <h3 class="pngfix">Table Of Contents</h3>
  157         <ul>
  158 <li><a class="reference internal" href="#">Application Schema Resolution</a><ul>
  159 <li><a class="reference internal" href="#schema-downloading-is-now-automatic-for-most-users">Schema downloading is now automatic for most users</a></li>
  160 <li><a class="reference internal" href="#resolution-order">Resolution order</a></li>
  161 <li><a class="reference internal" href="#oasis-catalog">OASIS Catalog</a></li>
  162 <li><a class="reference internal" href="#classpath">Classpath</a></li>
  163 <li><a class="reference internal" href="#cache">Cache</a></li>
  164 </ul>
  165 </li>
  166 </ul>
  167 
  168         <div class="section-footer"></div>
  169       </div>
  170         <div class="section">
  171           <h3>Continue Reading</h3>
  172           <ul>
  173             <li>Previous: <a href="mapping-file.html" title="previous chapter">Mapping File</a></li>
  174             <li>Next: <a href="supported-gml-versions.html" title="next chapter">Supported GML Versions</a></li>
  175           </ul>
  176         </div>
  177         <div class="section">
  178         <h3>This Page</h3>
  179         <ul class="this-page-menu">
  180                 
  181         <li><a href="https://github.com/geoserver/geoserver/tree/master/doc/en/user/source/data/app-schema/app-schema-resolution.rst">Edit</a></li>
  182         </ul>
  183         </div>
  184   </div><!-- /#sidebar -->
  185   </div><!-- /.wrap> -->
  186 </div><!-- /#main -->
  187 <div id="footer">
  188   <div class="wrap">
  189     &copy; Copyright 2020, Open Source Geospatial Foundation. License <a href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution</a>.
  190     Last updated on Nov 19, 2020.
  191     Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
  192   </div><!-- /.wrap> -->
  193 </div><!-- /#footer -->
  194   </body>
  195 </html>