Considering following Source Handler declaration in cocoon.xconf:

<protocol
    class="fr.paris5.shaman.spirit.insightsource.InsightSourceFactory"
    name="insight-content"
/>

We want this protocol to be supported, in order to allow following calls from Cocoon Sitemap:

<map:match type="publication-format" pattern="RAW" >
  <map:read src="insight-content:/{1}" />
</map:match>

or:

<map:match type="publication-format" pattern="MY-FORMAT" >
  <map:match pattern="**.html" >
    <map:generate src="insight-content:/{1}.xml" />
    <map:serialize type="html" />
  </map:match>
</map:match>

Both forms access to Insight content, via the insight-content: pseudo-protocol.

According to Spirit-tailored URLs, transmitted URIs contain a prefix (like ~top-nn/ or ~pub-nn/) giving a mean to find the right Publication.

A Source object is able to deliver an InputStream, plus some information about validity (for cache update). It is used by Cocoon instead of URLs when custom protocols are required, which is the case here.