This document springs from some offline discussion and thence  IDP-1172 - Getting issue details... STATUS  

The use of the nouns "file" and "resource" as well as their manifestations (respectively: "things on disk", and "things representable as a url" as well Spring Resources, Shibboleth Resources and other things that other packages use the term "resource" for) has caused significant confusion.  

In V4 it would be nice to

• either rationalise this
• or if we leave things alone, understand why we have.

This document describes the current state of play and tries to develop a plan for V4, and hence V3.4,

Current status

The first stage here is to understand what the current state of play is.  The following information was harvested by searching the the following terms in the schema files

• file
• resource
• classpath
• script
• input

Summary

We mostly use the term "file" and this is usually converted to a (Spring) resource using FilesystemGenericApplicationContext.  In these situations specifying a path will "do the right thing", but (should we choose to document it) the user has the option to say "file="classpath:\\WEB-INF\foobar" (or whatever the Spring syntax is)

In some cases the file has to be a file, often because it is writable, sometimes because of history.  For this reason alone it is probably a good idea to either not mention the possibilty of saying classpath:\\foo or hedging it around with disclaimers.

Filters

Scripted (Matcher and PolicyRule)

<ScriptFile>String</StringFile>

consumed as a (Spring) Resource.  Converted by spring (via FilesystemGenericApplicationContext) (so <ScriptFile>classpath:foo</ScriptFile> would work)

Attribute Resolver

Scripted Resolver and DataConnector

<ScriptFile>String</StringFile>

consumed as a (Spring) Resource.  Converted by spring (via FilesystemGenericApplicationContext)

All DataConnectors

springResources=”whatever”

consumed as a (Spring) Resource.  Converted by spring (via FilesystemGenericApplicationContext)

RelationalDatabase <ContainerManagedConnection>

resourceName=“what”

used as a string in doing the JNDI thing.  Nothing to do with files or Spring Resources

Metadata

FileBackedHTTPMetadataResolver

backingFile=”String”

consumed as String, converted in the setter to a java.io.File

FilesystemMetadataProvider

metadataFile=”String”

consumed as a Java.io.File, converted by Spring

SignatureValidation (filter)

certificateFile=”String”

This is a two part conversion.  The parser passes a string to a  FactoryBean which consumes it as a Resource (and hence the conversion is using Spring via FilesystemGenericApplicationContext).  The FacotryBean then does the explicit conversion to a X509Certificate in its doCreateInstance() code.

ResourceBackedMetadataProvider <HttpResource>

Deprecated and warned

url=”string”

url passed directly to HTTPMetadataResolver 

ResourceBackedMetadataProvider <FileBackedHttpResource>

Deprecated and warned

url=”string”, file=”string”

url passed directly, file passed to FileBackedHTTPMetadataResolver as a string.  Converted into a java.io.File in the constructor

ResourceBackedMetadataProvider <FilesystemResource>

Deprecated and warned

file=”string”

Consumed (in as FilesystemMetadataResolver) a java.io.File (converted by spring)

ResourceBackedMetadataProvider < ClasspathResource>

file=”string”

consumed (in spring.io.ClasspathResource) as a string, shimmed into to a Shibboleth resource and passed on to a ResourceMetadataResolver.

ResourceBackedMetadataProvider < SVNResource>

Don’t ask.

ResourceBackedMetadataProvider < Chaining>

Unsupported.  Fails during parsing

ResourceBackedMetadataProvider < Any> <PropertyReplacement>

Not supported

EntityAttribute (filter)

<AttributeFilterScript> and <ConditionScript> with child <ScriptFile>String</StringFile>

consumed as a (Spring) Resource. Converted by spring (via FilesystemGenericApplicationContext)

RelyingParty

N/A - this will be removed in V4

Resource

Used in the security schema for TrustEngines and for the ResourceBackedMetadataProvider

Security

X509Filesystem

<Certificate>, <PrivateKey>, <CRL>  all take a string

Consumed in a builder as a Resource (i.e. converted by spring via FilesystemGenericApplicationContext ) and converted and passed on as  javax.security.PrivateKey, ava.security.cert.X509Certificate, java.security.cert.CRL

BasicFileSystem, BasicResourceBacked (Credential)

<SecretKey>, <PrivateKey>, <PublicKey> : all take a string

Consumed in a builder as a Resource (i.e. converted by spring via FilesystemGenericApplicationContext ) and converted and passed on as javax.crypto.SecretKey, javax.security.PrivateKey, javax.security.PublicKey

PKIXFileSystem

Unsupported so N/A

Service interface

This is not a custom interface but it is deeply to do with resources, so it is worth pointing out that the primacy interface to service configuration is a List<Resource> .  Further such configuration is more like to be implemented by non file Resources (Http, Classpath and SVN)

V4 Suggestions

Having bottomed this out it seems that what we have is not unreasonable.  In most cases we can state that something is a file, even if we know that it is a resource; that way we never have to describe why something else which is a file cannot be a resource.  There are a few edge cases where a resource might be useful (service and metadata) this is called out explicitly

Mixed mode custom files

By this I mean

<AttributeResolver>
   <AttributeDefinition />
   <DataConnector />
   <beans xmlns="http://www.springframework.org/schema/beans">
      <bean ....>
   </beans>
</AttributeResolver>

This is dealt with in  JSE-18 - Getting issue details... STATUS

SVN (and friends) Resource

The suggestion here is that the SVN resource is replaced by a new one which is supplied with a java.lang.Runnable or a command line which called either in response to certain events (like the SVN Resource), or on a fixed timer.

Configuration would be something like

<bean parent="shibboleth.ReloadingResource" id="myconfig" path="/opt/idp/repo/file.xml" refresh="cd /opt/idp/repo; svn up"/>

Relying Party Schema

We are going to jettison this.

Security Schema

It would be nice to jettison this, but apart its major use in the V2 relying party syntax, it is also used in several other schema

• LDAP Data connector (StartTLSTrustCredential, StartTLSAuthenticationCredential )
• HTTP Client behavior:
  • HTTPMetadata resolvers (TLSTrustEngine), 
  • Potentially the REST Data connector
• Metadata SignatureValidation Filte (TrustEngine)

If possible, it would be nice jettison this? However doing so would require easier to use mechanisms for the common case (certificates in files) and full documentation on how to configure native spring homologs..

Resource Schema

With the security schema gone this is only ever used in the ReourceBackedMetadataProvider.  I suggest that we only support (the existing) resource-ref="beanId", although we could add

<MetadataProvider xst:type="ResourceBackedMetadataProvider" classpath="/META-INFO/foo/bar.xml"/>
<MetadataProvider xst:type="ResourceBackedMetadataProvider" path="/opt/idp/repo/file.xml" refresh="cd /opt/idp/repo; svn up"/>

Either way, the need for any elements in the resource schema goes away.

New Schema?

Are people unwilling to use native syntax?  Do we need new custom syntax and if so what for?  Can we become more dynamic in our handling (the way that the SP does)? 

V3.4 Requirements

Given the desire that V4 should consume any V3.4 configuration which loads without warning, we need to make changes to V3.4

• Introduce the replacement for the SVN resource (and warn on current use)
• Review (and if needed introduce) new mechanisms for TrustEngine consturction and warn on use
• Warn on all deprecated schema
• Do we want to test the water with  mixed mode parsing (maybe do it for one schema but do not document or support it?)