Class NDArrayFactory


  • public class NDArrayFactory
    extends java.lang.Object
    Manufactures NDArray objects from URLs. Methods are available to construct a readable NDArray from a URL pointing to an existing array resource, or to construct a new NDArray with a location given by a URL.

    This factory delegates the actual NDArray creation to external ArrayBuilder objects; the URL is passed to each one in turn until one can make an NDArray object from it, which object is returned to the caller.

    By default, if the corresponding classes are present, the following ArrayBuilders are installed:

    • uk.ac.starlink.hds.HDSArrayBuilder
    • uk.ac.starlink.fits.FitsArrayBuilder
    Consult the documentation of these classes to find out about the format of URLs understood by each.
    Author:
    Mark Taylor (Starlink)
    • Constructor Summary

      Constructors 
      Constructor Description
      NDArrayFactory()
      Constructs an NDArrayFactory with a default list of builders.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.util.List getBuilders()
      Gets the list of builders which actually do the URL->NDArray construction.
      NDArray makeNDArray​(java.lang.String location, AccessMode mode)
      Constructs a readable NDArray from a location representing an existing resource.
      NDArray makeNDArray​(java.net.URL url, AccessMode mode)
      Constructs a readable NDArray from a URL representing an exisiting resource.
      NDArray makeNewNDArray​(java.lang.String location, NDArray template)
      Constructs a new NDArray to which data can be written given a location and another template NDArray.
      NDArray makeNewNDArray​(java.lang.String location, NDShape shape, Type type, BadHandler bh)
      Constructs a new NDArray to which data can be written given a location and the array characteristics.
      NDArray makeNewNDArray​(java.net.URL url, NDArray template)
      Constructs a new NDArray to which data can be written given a URL and another template NDArray.
      NDArray makeNewNDArray​(java.net.URL url, NDShape shape, Type type, BadHandler bh)
      Constructs a new NDArray to which data can be written given a URL and the array characteristics.
      void setBuilders​(ArrayBuilder[] builders)
      Sets the list of builders which actually do the URL->NDArray construction Builders earlier in the list are given a chance to handle a URL before ones later in the list.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • NDArrayFactory

        public NDArrayFactory()
        Constructs an NDArrayFactory with a default list of builders.
    • Method Detail

      • getBuilders

        public java.util.List getBuilders()
        Gets the list of builders which actually do the URL->NDArray construction. Builders earlier in the list are given a chance to handle a URL before ones later in the list. This list may be modified to change the behaviour of the NDArrayFactory.
        Returns:
        a mutable List of ArrayBuilder objects used for turning URLs into NDArrays
      • setBuilders

        public void setBuilders​(ArrayBuilder[] builders)
        Sets the list of builders which actually do the URL->NDArray construction Builders earlier in the list are given a chance to handle a URL before ones later in the list.
        Parameters:
        builders - an array of ArrayBuilder objects used for turning URLs into NDArrays
      • makeNDArray

        public NDArray makeNDArray​(java.net.URL url,
                                   AccessMode mode)
                            throws java.io.IOException
        Constructs a readable NDArray from a URL representing an exisiting resource. A null result will be returned if none of the available builders understands the URL; an IOException will result if one of the builders is willing to handle the URL but fails to find an array resource at it.
        Parameters:
        url - a URL pointing to a resource holding array data
        mode - the mode with which it should be accessed
        Returns:
        a readable NDArray object view of the data at url, or null if one could not be found
        Throws:
        java.io.IOException - if there is any I/O error
      • makeNewNDArray

        public NDArray makeNewNDArray​(java.net.URL url,
                                      NDShape shape,
                                      Type type,
                                      BadHandler bh)
                               throws java.io.IOException
        Constructs a new NDArray to which data can be written given a URL and the array characteristics. A null result will be returned if none of the available builders understands the URL; an IOException will result if one of the builders is willing to handle the URL but fails to make an array resource at it.

        The bh parameter indicates a requested bad value handling scheme, but does not guarantee that it will be used, since not all storage formats are capable of storing bad values in arbitrary ways. According to the resource type, bad value handling will be provided on a best-efforts basis. If bh is null, the implementation will choose a bad value handling policy of its own.

        Parameters:
        url - a URL pointing to a writable resource. This may be a suitable file:-protocol URL or one with some other protocol which can provide an output-capable connection
        shape - the shape of the new array
        type - a Type object indicating the type of data in the array
        bh - the requested bad value handling policy - see above.
        Returns:
        a new writable NDArray object with the given URL, or null if none could be constructed because none of the handlers recognised the URL
        Throws:
        java.io.IOException - if an I/O error occurs
        java.lang.IllegalArgumentException - if the type of bh does not match type
      • makeNewNDArray

        public NDArray makeNewNDArray​(java.net.URL url,
                                      NDArray template)
                               throws java.io.IOException
        Constructs a new NDArray to which data can be written given a URL and another template NDArray. This convenience method simply calls makeNewNDArray(URL,NDShape,Type,BadHandler) with the shape, type and bh parameters copied from the template NDArray.
        Parameters:
        url - a URL pointing to a writable resource. This may be a suitable file:-protocol URL or one with some other protocol which can provide an output-capable connection
        template - an NDArray whose characteristics are to be copied when the new one is created
        Returns:
        a new writable NDArray object with the given URL
        Throws:
        java.io.IOException - if an I/O error occurs
      • makeNDArray

        public NDArray makeNDArray​(java.lang.String location,
                                   AccessMode mode)
                            throws java.io.IOException
        Constructs a readable NDArray from a location representing an existing resource. This convenience method just turns the location into a URL and calls makeNDArray(URL,AccessMode).
        Parameters:
        location - the location of the resource. If it cannot be parsed as a URL, it will be treated as a filename
        mode - the mode with which it should be accessed
        Returns:
        a readable NDArray object view of the data at location, or null if one could not be found
        Throws:
        java.io.IOException - if there is any I/O error
      • makeNewNDArray

        public NDArray makeNewNDArray​(java.lang.String location,
                                      NDShape shape,
                                      Type type,
                                      BadHandler bh)
                               throws java.io.IOException
        Constructs a new NDArray to which data can be written given a location and the array characteristics. This convenience method just turns the location into a URL and calls makeNewNDArray(URL,NDShape,Type,BadHandler)
        Parameters:
        location - the location of the resource. If it cannot be parsed as a URL, it will be treated as a filename
        shape - the shape of the new array
        type - a Type object indicating the type of data in the array
        bh - requested bad value handling policy
        Returns:
        a new writable NDArray object at the given location, or null if none could be constructed because none of the handlers recognised the URL
        Throws:
        java.io.IOException - if an I/O error occurs
      • makeNewNDArray

        public NDArray makeNewNDArray​(java.lang.String location,
                                      NDArray template)
                               throws java.io.IOException
        Constructs a new NDArray to which data can be written given a location and another template NDArray. This convenience method just turns the location into a URL and calls makeNewNDArray(URL,NDArray).
        Parameters:
        location - the location of the resource. If it cannot be parsed as a URL, it will be treated as a filename
        template - an NDArray whose characteristics are to be copied when the new one is created
        Returns:
        a new writable NDArray object at the given location
        Throws:
        java.io.IOException - if an I/O error occurs