ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Stephen McConnell" <mcconn...@dpml.net>
Subject RE: Resource.getURL() - example
Date Sat, 30 Sep 2006 19:34:20 GMT

Looking at options that have been put forward following Matt's request for
comment it seems to me that the actual requirements are still too loose.  

However - I do think we can break down some different topics:

  1. namespaced resources

     the support within Ant for named resources associated 
     with a namespace identifying a particular type of 
     feature (e.g. property:foo, zip:bar, etc.)

  2. using a foreign URL as local file source

     the ability within Ant to support supplied URL instances 
     (and please note that I'm talking about a URL instance 
     as opposed to a uri String and as such I'm precluding 
     any discovery issues) when constructing collections of 
     references such as Path instances

  3. enabling url protocol handler registration in a build file

     the ability within Ant to recognize String urn values 
     and construct properly populated URL instances without
     dependence on the underlying JVM discovery mechanisms
     based on data declared in a build file

  4. URL publication where Ant is the data source

     the ability of Ant to publish URL instances (and note 
     that I'm again referring to properly populated URL 
     instances) that can be resolved by client applications
     without reference or dependence on the Ant API but with
     a valid client assumption that resolution of streams or 
     content against that URL will return a valid value 
     derived from an Ant project references by the URL 
     connection

Each of the four requirements identified so far represent distinct problems.
If addressed separately there are some identifiable actions that could be
taken (or not taken), and some identifiable relationships between these
requirements and operation features and usability within Ant 1.7.

1. Namespaced Resources
-----------------------

The 1.7 codebase includes the Resource class and a number of derived
classes. A question was raised concerning the addition of the method
getURL() on the Resource class and this in turn brought about discussion of
custom protocol handlers and a bunch of other stuff.  Within the thread a
number of points have been raised concerning the existing classes and their
relationship to URLs, local files, and urns.  For the moment I'm going to
suggest that we exclude URL publication on the grounds that a URL instance
makes sense when publishing data about a project to a client that will use
the URL without reference (or knowledge of) Ant - and I think such a feature
is not justified at this time (even though it does open up a host of
interesting possibilities for advanced applications that embed Ant).

I do think that some clarification is needed with respect to URLResource as
there are at least three possible roles of a URL:

  a) where the supplied URL is the value
  b) where the supplied URL is the source of the value
  c) where the supplied URL is the source of a custom resource

I think item (a) can be excluded on the grounds that this is really a
property concern (i.e. the URL value is the value of a property).  Item (b)
is IMO the genuine concern - however, the concern detailed under item (c)
needs to be addressed.  Specifically, item (c) could be resolved through the
addition of a ResourceFactory into the Ant API and within which the result
of applying something like the following operation on a URL argument would
establish a resource type:

     Resource resource = (Resource) url.getContent( new
Class[]{Resource.class} );

I would also note that given ResourceFactory, the need for URLResource as a
distinct resource type becomes questionable as it seems to me that
everything needed (in terms of methods) is already available under the
Resource class.  Also, I'll come back to the subject of Resource.getURL()
later in this email when addressing the forth item - 'URL publication'.

I also should note that given a resource factory, the utility of such a
factory is limited to API only usage unless a framework is provided in Ant
for the registration of URL protocol handlers (unless a enclosing
application context is established).  Put more simply - if a build file
contains a foreign uri and if we want that uri to be usable, then we need a
framework to declare a hander to use when constructing URL instances
internally within Ant - and this is the subject addressed under point (3)
'enabling url protocol handler registration in a build file'.

2. Using Foreign URLs
---------------------

Item (2) deals with subject of Ant's support within the API for foreign URLs
and in effect dealing with the issue that the current codebase does not
provide good support for protocols other than "file" in the establishment of
local file references.  This subject can be subdivided into two distinct
concerns.

  a) extraction of a File instance from a URL
  b) identification of Resource instances that support 
     exposure of local File instance

Item (a) can be resolved by employing the following convention:

     File file = (File) url.getContent( new Class[]{File.class} );

If the resulting file instance is null then the supplied URL is invalid,
otherwise everything folds nicely into the existing API assumptions.  There
is the presumption here that the Path instance (and possibly other classes)
need to expose appropriate createXxxx( URL url ) methods through which file
paths resolved using the above technique may be added to path collections.

Item (b) has already been discussed and resolves around the premise that
FileResource should not be the definition of the base for resources that can
be resolved to a File value.  Based on the reply from Stefan on this subject
it seems that this is reasonably easy to resolve using something like a
LocalFileProvider interface.

There is also the underlying but separate issue of the ability within Ant to
recognize and bind a protocol handler when creating a new URL instance as
this is the feature that lets us declare urn strings in a build file with
knowledge that Ant can bind and resolve them properly - which is addressed
under the next 'enabling url protocol handler registration in a build file'.

3. Enabling URL protocol handler registration in a build file
-------------------------------------------------------------

The discussion concerning resources and foreign URLs has been focussed
primarily of the usage of the Ant API by a client application (e.g. a
container establishing, configuring and executing an Ant project).  In this
scenario URLs passed as arguments in methods exposed on the Ant API can be
established with a protocol handler and as such no handler discovery is
required.  However - this precluded the possibility of using custom
protocols as string arguments in attributes within build files.  

Within this thread we have already covered the discovery mechanisms used by
the JVM (including stream handler factories and the usage of system
classloader manipulation in conjunction with the java.protocol.handler.pkgs
system property).  The result of that discussion was the establishment of a
rational strategy for the explicit declaration of handlers at the Ant
application level and the potential for Ant to locate and bind handlers when
constructing new URL instances.  The solution involved the addition of a
ClassResource (extending JavaResource) and HandlerResource (extending
ClassResource) where a name is associated to a loaded class and the name is
used to locate a custom protocol handler based on the uri scheme name.  This
should be trivial to implement and requires no knowledge of custom handlers
or connections.

The build.xml view of this would be something like:

  <handler id="artifact" class="net.dpml.transit.artifact.Handler">
    <classpath>
      <pathelement location="my-handler-jar.jar"/>
    </classpath>
  </handler>

  <path id="my-path">
    <pathelement uri="artifact:jar:acme/widget"/>
  </path>

Given the ability to declare handlers we can then move forward with much
more clarity because Ant will be open via a standard extension mechanism -
and with recognition of uris in areas such as resource creation, things will
be looking really good.

4. URL publication where Ant is the data source
-----------------------------------------------

In everything described above - there is no requirement for any
implementation within Ant of custom URL protocol handlers.  In effect, by
breaking out the separate issues of incoming URLs, incoming uris (urls as
strings), and the url to file issue, we are left with the separate concern
of URL creation and publication by the Ant runtime.  I should note that I am
not addressing strignified urls such as 'property:foo' on the grounds that
these values will appear in a context where it is known to be a resource
reference.  I am only addressing the potential publication of something like
'property:foo' as a URL instance - e.g. 

  URL url = new URL( context, 'property:foo', handler );

The ultimate objective of reviewing the above line is two-fold.  Firstly - I
want to examine what each of the arguments represent, and secondly - I want
to establish the potential value that a URL provides.  Starting of with the
arguments - we have:

  a) the context - which inevitable resolves down to an Ant 
     project instance

     - an identifiable instance
     - or, the current ant instance

  b) the resource identifier urn (e.g. 'property:foo')

     - a feature type (property)
     - a feature name (foo)

  c) the protocol handler

     - a factory for the 'property' protocol connection
     - an implementation of a URLConnection for property
       that knows how to resolve a value for the named 
       resource relative to the current or identified
       project context

Given the above we need to keep in mind that identifiable Ant project
instances are IMO out-of-scope without substantial development of the Ant
runtime, so I think its reasonable to presume that the context is any
current Ant project instance.  However - if a current project instance is a
prerequisite, then there is no need for a URL because Ant is already in
scope and as such simple string urn values handled by the Ant runtime are
sufficient (a.k.a. the application managed scenario). Anyone who has been
following this thread closely will probably recognize that this conclusion
is inconsistent with earlier comments from myself.  In effect, I think the
process of breaking out concerns 1, 2, and 3 have enabled the removal of
several related subjects (combined with the fact that some quick prototypes
from yesterday conformed to me that this thread was mixing too many
concerns).

Conclusion
----------

  1. some cleanup is needed with respect to URLResource 
     and potential factory semantics
  2. better support should be added for foreign file capable 
     urls in Path and other collection classes
  3. url handler registration should be included with emphasis
     this this is a big feature plus and a small code impact
  4. that Resource.getURL() is not required given the above
  5. that items (1) and (2) require item (3) when we move from
     the API to the build file

Hoping that this is useful ...

Cheers, Steve.

--------------------------
Stephen McConnell
mailto:mcconnell@dpml.net
http://www.dpml.net
 





 













---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org


Mime
View raw message