cogAn abstraction of a XWiki URI (Entity, Template, Skin, etc)
TypeJAR
Developed by

XWiki Development Team

Active Installs0
Rating
Rate!
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Enterprise

Installable with the Extension Manager

Description

A resource in XWiki represents something that can be accessed. For example: Entities, Templates, Skin files, Files on the filesystem, Temporary files generated by Macros, etc.

It can be viewed as a URI or as an abstraction of an XWiki URL.

API Tour

The following classes/interfaces are available:

  • ResourceType: Represents a type of Resource (eg Entities, Templates, Skin files, Files on the filesystem, Temporary files generated by Macros, etc).
  • ResourceReference: represents a reference to a Resource. EntityResourceReference represent a reference to an Entity resource (document, space, page, wiki, etc).
  • ResourceTypeResolver: Extract the ResourceType from a representation (text, URL, etc). 7.1M1
  • ResourceReferenceResolver: Create a ResourceReference object from a representation (text, URL, etc). For example the StandardURLResourceReferenceResolver is used to create a ResourceReference out of an URL written using the "standard" format.
  • ResourceReferenceSerializer: A component role type to convert a Resource reference into something else. For example the URL module provides a StandardExtendedURLResourceReferenceSerializer to generate a URL out of of Resource reference (note that the implementation is not complete as of now and shouldn't be used for the moment).
  • ResourceReferenceManager: Provides a getResource() method to access the current resource being processed (located in the Execution Context).
  • ResourceLoader: Load Resources pointed to by Resource Reference as an Input Stream (not used yet)
  • EntityResourceAction: Represents the action to be executed on an Entity Resource (eg view, delete, get, etc).
  • ResourceReferenceHandler: Handles a ResourceReference by executing some actions. For example, for the bin Resource type (which is an Entity Resource Type) this means executing the various actions (eg view, edit, download, etc) for that Entity.
  • ResourceReferenceHandlerManager: Entry point for handling Resource References. Will find the proper ResourceReferenceHandler which know how to handle that Resource type and will them in the right priority order.

Resource Reference Handling

This part of the Resource module is in charge of calling the correct backend code to display what the user has asked for (it's the Controller in MVC terminology).

Right now most most Actions are still implemented the old way in the oldcore module without Components and using Struts. The goal is to progressively rewrite them using this new Resource Reference Handler API. Check the WebJars Module For an example of registering a new ResourceType and ResourceReferenceHandler.

This API supports the following use cases:

  • UC1: Handlers should be able to be added without touching at the existing platform code (i.e. someone could write a new Handler in java and plug it in)
  • UC2: It should be possible to execute something before or after an Handler's execution.
  • UC3: It should be possible to completely replace a Handler with another implementation.
  • UC4: It should be possible to add Handlers without stopping the running XWiki instance
  • UC5: Handlers should not know about each other
  • UC6: Handlers should be independent of the URL formats used
  • UC7: Handlers should work for any type of Resource (Entity Resources, Temporary Resources, Skin Resources, etc)
  • UC8: It should be possible for a Handler to be registered for one Resource type, a list of Resource types or all types

Adding a new Resource Type Handler

XWiki 7.1M1 Extensions can register a new URL Resource Type. 

When installing an Extension that contain some new Resource Type (and thus some ResourceReferenceResolver implementation), it must be installed on the farm (and not on a wiki) so that it is registered against the root Component Manager. It won't work otherwise, as using a Wiki Component Manager requires to know the wiki and knowing the wiki requires parsing the URL and parsing the URL depends on the Resource Reference Resolver to use...

Here's an example of a webjars Resource Type that would be called for the following types of URLs: http://<server>/<context path>/webjars/<path/to/resource/>.

@Component
@Named("webjars")
@Singleton
public class WebJarsResourceReferenceHandler extends AbstractResourceReferenceHandler<ResourceType>
{
   /**
     * The WebJars Type.
     */

   public static final ResourceType TYPE = new ResourceType("webjars");

   @Override
   public List<ResourceType> getSupportedResourceReferences()
   {
       return Arrays.asList(TYPE);
   }

   @Override
   public void handle(ResourceReference resourceReference, ResourceReferenceHandlerChain chain)
       throws ResourceReferenceHandlerException
   {
       [...]
   }
}

Adding a new Entity Resource Type Handler

Entity Resource References are handled by a ResourceReferenceHandler component with hint bin (that name corresponds to the part of the URL showing that it's a URL about an Entity). That ResourceReferenceHandler, in turn, looks for ResourceReferenceHandler components that are registered for the EntityResourceAction to execute (view, edit, download, etc) and calls them in the right priority order.

Here's an example of a webjars Entity Resource Action that would be called for the following types of URLs: http://<server>/<context path>/bin/webjars/resource/path?value=<resource name>.

@Component
@Named("webjars")
@Singleton
public class WebJarsResourceReferenceHandler extends AbstractResourceReferenceHandler<EntityResourceAction>
{
   /**
     * The WebJars Action.
     */

   public static final EntityResourceAction ACTION = new EntityResourceAction("webjars");

   /**
     * Prefix for locating JS resources in the classloader.
     */

   private static final String WEBJARS_RESOURCE_PREFIX = "META-INF/resources/webjars/";

   @Inject
   private Container container;

   @Override
   public List<EntityResourceAction> getSupportedResourceReferences()
   {
       return Arrays.asList(ACTION);
   }

   @Override
   public void handle(ResourceReference reference, ResourceReferenceHandlerChain chain)
       throws ResourceReferenceHandlerException
   {
        String resourceName = reference.getParameterValue("value");
        String resourcePath = String.format("%s%s", WEBJARS_RESOURCE_PREFIX, resourceName);

        InputStream resourceStream = getClassLoader().getResourceAsStream(resourcePath);

       if (resourceStream != null) {
           try {
                IOUtils.copy(resourceStream, this.container.getResponse().getOutputStream());
           } catch (IOException e) {
               throw new ResourceReferenceHandlerException(
                    String.format("Failed to read resource [%s]", resourceName), e);
           } finally {
                IOUtils.closeQuietly(resourceStream);
           }
       }

       // Be a good citizen, continue the chain, in case some lower-priority Handler has something to do for this
       // Resource Reference.
       chain.handleNext(reference);
   }

   /**
     * @return the Class Loader from which to look for WebJars resources
     */

   protected ClassLoader getClassLoader()
   {
       // Load the resource from the context class loader in order to support webjars located in XWiki Extensions
       // loaded by the Extension Manager.
       return Thread.currentThread().getContextClassLoader();
   }
}

Known Resource Types

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-resource-api 9.9):

  • org.xwiki.commons:xwiki-commons-context 9.9
Tags:
Created by Vincent Massol on 2013/10/28 11:51
    

Get Connected