Package com.orchestranetworks.schema

# Class SchemaLocation

java.lang.Object
com.orchestranetworks.schema.SchemaLocation

public abstract class SchemaLocation extends Object
Identifies a data model location, which can be either based on a URL (standard notation) or a module.

When a location is based on an EBX® module, this implies that the data model is packaged inside the specified module (which is commonly a web application). This approach has several benefits:

- an easier and standardized deployment procedure for different application servers;
- more independence regarding physical deployment;
- the packaging of resources used by the data model (constraints, functions, bean editors, etc.) in the module.

EBX® defines specific URNs to identify a data model location. The following table describe all supported URNs.

URN | Description
--- | ---
`urn:ebx:publication:<aPublicationName>` | Identifies an embedded data model, where `<aPublicationName>` is the name of a publication that was created by publishing an embedded data model in the data model assistant.
`urn:ebx:module:<aModuleName>:<aPathInModule>` | Identifies a packaged data model inside a module, where `<aModuleName>` is the name of the module containing the data model and `<aPathInModule>` is the path of the data model inside the module.

As the above URNs are specific to EBX®, they will not be able to be resolved by external tools. Thus, when using an external editor to edit any XML Schema Documents that contain these URNs, the editor may report errors. To workaround this issue, you can manually substitute the physical locations of the targeted XML Schema documents for the URNs during editing of the XML Schema document using an external editor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static final SchemaLocation`
  `forLocation(String aBaseOrNull, String aURI)`
  Returns a reference to an embedded data model (not packaged inside an EBX® module).
  `abstract String`
  `format()`
  Returns a string representation of the location of this data model.
  `static final SchemaLocation`
  `forPathInModule(String aPathInModule, String aModuleName)`
  Returns a reference to a data model that is packaged inside an EBX® module.
  `abstract File`
  `getFileOrNull()`
  If this location resolves to a file, returns that file, otherwise returns `null`.
  `abstract InputStream`
  `getInputStream()`
  Deprecated.
  This method has been replaced by `getInputStream(Repository)`.
  `abstract InputStream`
  `getInputStream(Repository aRepository)`
  Returns a stream for reading the content of the corresponding data model.
  `abstract String`
  `getModuleName()`
  Returns the name of the module that contains the resource or, if this instance is URI based, returns the default module name.
  `String`
  `getPathInModule()`
  Returns the location of the related data model inside its container module if it is packaged in a module.
  `String`
  `getPublicationName()`
  Returns the name of the publication if this instance is an embedded data model.
  `abstract boolean`
  `isPackagedInModule()`
  Returns `true` if this instance is a module-based location.
  `abstract boolean`
  `isPublication()`
  Returns `true` if this instance refers to a publication.
  `abstract boolean`
  `isReserved()`
  Returns `true` for data models that are managed by EBX®.
  `abstract boolean`
  `isURI()`
  Returns `true` if this instance is a URL-based location.
  `static final SchemaLocation`
  `parse(String aURN)`
  Returns a `SchemaLocation` based on the string specified.
  `abstract SchemaLocation`
  `resolve(String aURI)`
  Returns the most accurate locator constituting the real target with this current instance as the base name.
  `abstract String`
  `toStringInfo(Locale aLocale)`
  Returns a string that identifies this location.

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### forLocation

    public static final SchemaLocation forLocation(String aBaseOrNull, String aURI) throws IllegalArgumentException
    Returns a reference to an embedded data model (not packaged inside an EBX® module).

    Warning: Beyond simple test cases, it is generally recommended to use data models that are packaged inside EBX® modules (see `forPathInModule(String, String)`).

    The location of the data model is determined as follows:

    - If `aURI` is absolute, the location is `aURI`.
    - If `aURI` is relative, it uses `aBaseOrNull` as the base URI for resolving the location. If `aBaseOrNull` is `null`, it uses the current user directory, as defined by `File`, as the base URI.
    Parameters:
      `aBaseOrNull` - used only if `aURI` is relative
      `aURI` - an absolute or relative URI
    Throws:
      `IllegalArgumentException` - if an argument is not a well-formed URI
    See Also:
      - RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax

  - ### forPathInModule

    public static final SchemaLocation forPathInModule(String aPathInModule, String aModuleName)
    Returns a reference to a data model that is packaged inside an EBX® module.

    ##### Example

         SchemaLocation dataModelLocation = SchemaLocation.forPathInModule(
                "/WEB-INF/schemas/main.xsd",
                "sample");

    where "sample" is the module name.
    Parameters:
      `aPathInModule` - path of the data model inside the module (see example above). The path must be specified according to the rules detailed in `ServletContext.getResource(String)`).
      `aModuleName` - identifies the module that contains the data model (the name of a module is defined in the document `/WEB-INF/ebx/module.xml`, by the element `/module/name`).

  - ### getFileOrNull

    public abstract File getFileOrNull()
    If this location resolves to a file, returns that file, otherwise returns `null`.

    Generally, a location is able to resolve to a file if this location is URL-based with the protocol `file:`, or if this location is module-based and the application server is able to translate the module location to an actual file.

    See Also:
      - `ServletContext.getRealPath(java.lang.String)`

  - ### getInputStream

    @Deprecated public abstract InputStream getInputStream() throws Exception
    Deprecated.
    This method has been replaced by `getInputStream(Repository)`.
    Returns a stream for reading the content of the corresponding data model. This method is not supported for embedded data models or data models located inside the `repository` directory, since those must be resolved in the context of a repository.
    Throws:
      `Exception`

  - ### getInputStream

    public abstract InputStream getInputStream(Repository aRepository) throws Exception
    Returns a stream for reading the content of the corresponding data model. The specified repository is used for resolving the content of a data model contained in a repository. For instance, a repository is necessary for getting the content of an embedded data model or a data model located inside the `repository` directory .
    Throws:
      `Exception`

  - ### getModuleName

    public abstract String getModuleName()
    Returns the name of the module that contains the resource or, if this instance is URI based, returns the default module name. The name of a module is defined in the document `/WEB-INF/ebx/module.xml`, by the element `/module/name`.
    Throws:
      `IllegalStateException` - if this method is called on an embedded data model. Embedded data models must be resolved in the context of a repository.

  - ### isReserved

    public abstract boolean isReserved()
    Returns `true` for data models that are managed by EBX®.

  - ### isPackagedInModule

    public abstract boolean isPackagedInModule()
    Returns `true` if this instance is a module-based location.

  - ### getPathInModule

    public String getPathInModule()
    Returns the location of the related data model inside its container module if it is packaged in a module.

    Returns `null` if this instance does not refer to packaged data model.

    Since:
      6.1.0
    See Also:
      - `isPackagedInModule()`
      - `getModuleName()`

  - ### isURI

    public abstract boolean isURI()
    Returns `true` if this instance is a URL-based location.

  - ### isPublication

    public abstract boolean isPublication()
    Returns `true` if this instance refers to a publication. A publication is a data model embedded in an EBX® repository.
    Since:
      6.1.0
    See Also:
      - `getPublicationName()`

  - ### getPublicationName

    public String getPublicationName()
    Returns the name of the publication if this instance is an embedded data model.

    Returns `null` if this instance does not refer to an embedded data model.

    Since:
      6.1.0
    See Also:
      - `isPublication()`

  - ### resolve

    public abstract SchemaLocation resolve(String aURI) throws IllegalArgumentException
    Returns the most accurate locator constituting the real target with this current instance as the base name.
    Throws:
      `IllegalArgumentException` - If the given string violates RFC 2396

  - ### format

    public abstract String format()
    Returns a string representation of the location of this data model.
    See Also:
      - `parse(String)`
      - `SchemaLocation`

  - ### parse

    public static final SchemaLocation parse(String aURN)
    Returns a `SchemaLocation` based on the string specified.

    The specified string must have been generated by `format()`.

    Throws:
      `IllegalArgumentException` - if the specified URN does not correspond to a supported EBX® URN or if the specified URN correspond to a relative path.
    See Also:
      - `format()`

  - ### toStringInfo

    public abstract String toStringInfo(Locale aLocale)
    Returns a string that identifies this location.
    Parameters:
      `aLocale` - if `null`, uses the default locale.