Package org.apache.tapestry5.services

# Interface AssetSource

All Known Implementing Classes:
  `AssetSourceImpl`

@UsesMappedConfiguration(AssetFactory.class) public interface AssetSource
Used to find or create an `Asset` with a given path. Assets are defined with a domain, and the domain is indicated by a prefix. The two builtin domains are "context:" (for files inside the web application context) and "classpath:" for files stored on the classpath (typically, inside a JAR, such as a component library). Other domains can be defined via contributions to the AssetSource service. Since 5.1.0.0, is is preferred that `AssetFactory.createAsset(org.apache.tapestry5.commons.Resource)` return an instance of `org.apache.tapestry5.Asset2`. Since 5.7.0, Asset2 was merged into Asset and removed.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Asset`
  `getAsset(Resource baseResource, String path, Locale locale)`
  Finds the asset.
  `Asset`
  `getClasspathAsset(String path)`
  Obtains a classpath asset in the current locale (as defined by the `ThreadLocale` service).
  `Asset`
  `getClasspathAsset(String path, Locale locale)`
  Convenience for finding assets on the classpath.
  `Asset`
  `getComponentAsset(ComponentResources resources, String path, String libraryName)`
  Gets an asset that is used with, or injected into, a component, that will be exposed to the client.
  `Asset`
  `getContextAsset(String path, Locale locale)`
  Convenience for finding assets in the context.
  `Asset`
  `getExpandedAsset(String path)`
  As with `getUnlocalizedAsset(String)`, but symbols in the path are expanded}.
  `Asset`
  `getUnlocalizedAsset(String path)`
  Find an asset but does not attempt to localize it.
  `Resource`
  `resourceForPath(String path)`
  Finds the asset, either on the classpath or (if prefixed), within the indicated domain.

- ## Method Details

  - ### getAsset

    Asset getAsset(Resource baseResource, String path, Locale locale)
    Finds the asset. The path may either be a simple file name or a relative path (relative to the base resource) or it may have a prefix, such as "context:" or "classpath:", in which case it is treated as a complete path within the indicated domain. The resulting Resource is then localized (to the provided Locale) and returned as an Asset. The AssetSource caches its results, so a single Asset instance may be shared among many different components.
    Parameters:
      `baseResource` - base resource for computing relative paths, or null to search the classpath
      `path` - relative to the base resource
      `locale` - locale to localize the final resource to, or null for the thread's current locale
    Returns:
      the asset
    Throws:
      `RuntimeException` - if the asset can not be found

  - ### resourceForPath

    Resource resourceForPath(String path)
    Finds the asset, either on the classpath or (if prefixed), within the indicated domain. The result is not localized. The underlying Asset may not exist.
    Parameters:
      `path` - to the resource to provide as an Asset
    Returns:
      Resource for the path (the Resource may not exist)
    Since:
      5.1.0.0

  - ### getClasspathAsset

    Asset getClasspathAsset(String path, Locale locale)
    Convenience for finding assets on the classpath.
    Parameters:
      `path` - path to the base resource, relative to classpath root
      `locale` - to localize the resource to
    Returns:
      the asset
    Throws:
      `RuntimeException` - if the asset can not be found

  - ### getContextAsset

    Asset getContextAsset(String path, Locale locale)
    Convenience for finding assets in the context.
    Parameters:
      `path` - path relative to the base resource (the context root)
      `locale` - to localize the resource to, or null for the locale for the current request
    Returns:
      the asset
    Throws:
      `RuntimeException` - if the asset can not be found
    Since:
      5.1.0.0

  - ### getClasspathAsset

    Asset getClasspathAsset(String path)
    Obtains a classpath asset in the current locale (as defined by the `ThreadLocale` service).
    Parameters:
      `path` - relative to the classpath root
    Returns:
      the asset
    Throws:
      `RuntimeException` - if the asset can not be found

  - ### getUnlocalizedAsset

    Asset getUnlocalizedAsset(String path)
    Find an asset but does not attempt to localize it. If the path has no prefix, it is assumed to be on the classpath.
    Throws:
      `RuntimeException` - if the asset can not be found
    Since:
      5.2.0

  - ### getExpandedAsset

    Asset getExpandedAsset(String path)
    As with `getUnlocalizedAsset(String)`, but symbols in the path are expanded}.
    Since:
      5.2.0

  - ### getComponentAsset

    Asset getComponentAsset(ComponentResources resources, String path, String libraryName)
    Gets an asset that is used with, or injected into, a component, that will be exposed to the client. This encapsulates the new, in 5.4, standard that assets should all be stored in (sub-folders of) `META-INF/assets/library-name/`. This is the preferred location in 5.4, with compatibility for 5.3 that allows assets to be stored on the classpath alongside Java classes and server-only resources such as templates and message catalogs. When resolving a resource in a component that is subclass, the point of injection is the class which contains the injecting annotation (e.g., `Inject` with `Path`, or `Import`). In other words, the library name for the library containing the class, rather than the library name of the instantiated subclass (which can be different).
    Parameters:
      `resources` - resources, used to identify starting location of asset (if path does not include a asset prefix).
      `path` - path to the resource; either fully qualified (with an asset prefix such as "context:"), or relative to the component's library asset folder (the 5.4 and beyond way), or the to the component's Java class file (the 5.3 and earlier way, still supported until at least 5.5). Symbols in the path are expanded.
      `libraryName` - The name of the library containing the component, as per `ComponentModel.getLibraryName()`. For a subclass, the libraryName must reflect the name of the library for the parent class that forms the basis of injection.
    Returns:
      the Asset
    Throws:
      `RuntimeException` - if Asset can not be found
    Since:
      5.4