Package fi.tut.mei.capabilityQueryLib

Class Client

  • public class Client
extends Object
    Client is the main class when using cql programmatically. A Client instance is created from either just from the model ontology or from a resource instances ontology that contains actual resources. It can be used to get information like capabilities and resources from the ontology. It can calculate combined capabilities and their parameters for device combinations in the ontology. It can also generate combination possibilities for given capabilities by creating different combinations from the resources available in the ontology.
    Author:
    hylli

    • Constructor Detail

      • Client

        public Client()
        Create a ontology client using the default ontology defined in RESOURCE_ONTOLOGY_LOCATION

      • Client

        public Client​(String fileName)
        creates a ontology client that reads the ontology from the given source
        Parameters:
        fileName - name of the file containing the ontology. a local file or an url

    • Method Detail

      • setResourceOntology

        public void setResourceOntology​(String fileName)
        Set the resource instance ontology of the client. This assumes that the new ontology uses the same resource, capability and process taxonomy models that were processed when the client was built.
        Parameters:
        fileName - the ontology file or url

      • setOntology

        public void setOntology​(org.apache.jena.ontology.OntModel onto)

      • createOntologyModel

        public org.apache.jena.ontology.OntModel createOntologyModel​(InputStream content)
        Create memory based OWL model that uses client's own document manager not the global one.
        Parameters:
        content - If not null the content is read to the model.
        Returns:
        Ontology model with Client's document manager with the content if present.

      • setResourceOntology

        public void setResourceOntology​(InputStream input)
        Set the resource instance ontology of the client. This assumes that the new ontology uses the same resource, capability and process taxonomy models that were processed when the client was built.
        Parameters:
        input - InputStream containing the new resource instance ontology in the XML/RDF format

      • addResources

        public void addResources​(InputStream input)
        Add new resource instances to clients existing ones. These new instances have to use the same resource, capability, taxonomy and common concepts models.
        Parameters:
        input - InputStream containing a resource instances ontology in the xml/rdf format.

      • addResources

        public void addResources​(org.apache.jena.rdf.model.Model resources)
        Add new resource instances to clients existing ones. These new instances have to use the same resource, capability, taxonomy and common concepts models.
        Parameters:
        resources - a jena model containing a resource instance ontology

      • saveOntology

        public void saveOntology​(OutputStream output)
        Writes the client's ontology to the given stream.
        Parameters:
        output - stream where the client is written to

      • getParameter

        public Parameter getParameter​(String name)
        Get capability parameter with the given name.
        Parameters:
        name - parameter name
        Returns:
        parameter with the name. null if no parameter with the name

      • getParameterObject

        public ParameterObject getParameterObject​(String name)
        Get the parameter object with the given name.
        Parameters:
        name - name of a parameter object
        Returns:
        parameter object with the name. null if not found

      • viewParameters

        public List<String> viewParameters​(String capabilityName)
        List all parameters of a capability as list of strings. Strings represent the parameters as a hierarchy separated by / for example payload or hasRotationMovementRanges/RotationalMovementRange/rotation_z
        Parameters:
        capabilityName - name of a capability
        Returns:
        a string for each parameter and parameter of each ParameterObject, Null if there is no capability with the given name.

      • getOntologyFile

        public String getOntologyFile()
        Get the file path / URI used in creating this client. This is either the argument given to the constructor or if the default constructor was used the DEFAULT_RESOURCE_ONTOLOGY_LOCATION
        Returns:
        the ontology file used to create this client.

      • getProcessTaxonomyModel

        public ProcessTaxonomyModel getProcessTaxonomyModel()
        Get an object that holds information about the process taxonomy model.
        Returns:
        the process taxonomy model.

      • getDeviceCombination

        public DeviceCombination getDeviceCombination​(String name)
        Get information about a device combination. The information includes all devices, capabilities and combined capabilities for each device. Parameters with their values are also provided for individual devices and blueprints. Capability parameters are also provided for device combinations if the source ontology file contains them i.e. it was created with the saveAllDeviceCombinations(String, OntModel) method
        Parameters:
        name - the name of a device combination
        Returns:
        a device combination. null if no device combination with the given name

      • isAllCombinedCapabilityInfo

        public boolean isAllCombinedCapabilityInfo()
        Get if getting of some information should be omitted when getting information about devices or device combinations. This is used when generating combination possibilities or calculating combined capabilities for all combinations. In these cases not all information normally fetched is used
        Returns:
        the allCombinedCapabilityInfo

      • saveCombinedCapabilities

        public void saveCombinedCapabilities​(DeviceCombination device,
                                     String file)
                              throws FileNotFoundException
        Save device's combined capabilities and their calculated parameters to the given ontology file. This will include also combined capabilities of the parts.
        Parameters:
        device - A device combination
        file - Path to the ontology file where the info will be saved. Can be an existing file or if not a new file will be created.
        Throws:
        FileNotFoundException - file not found

      • saveAllDeviceCombinations

        public org.apache.jena.ontology.OntModel saveAllDeviceCombinations​(String file,
                                                                   org.apache.jena.ontology.OntModel onto)
                                                            throws FileNotFoundException
        Calculate combined capabilities and capability parameters for device combinations whose capabilities have not yet been calculated and save them into an ontology file.
        Parameters:
        file - Name of the file where the information is to be saved. If null information will be not saved into a file.
        onto - Ontology model where the information will be added. Can be null in which case a model is created for the information.
        Throws:
        FileNotFoundException - file not found

      • getSimpleCapabilitiesForDeviceCombination

        public Set<Capability> getSimpleCapabilitiesForDeviceCombination​(String device)
        get all of the simple capabilities of a device combination
        Parameters:
        device - the device name
        Returns:
        the capabilities

      • getCapability

        public Capability getCapability​(String name)
        get a capability by name
        Parameters:
        name - capability name
        Returns:
        the capability. Null if there is no such capability.

      • getCapabilityAssociation

        @Deprecated
public CapabilityAssociation getCapabilityAssociation​(String name)
        Deprecated.
        always returns null since capability associations no longer have names.
        Get a capability association by name
        Parameters:
        name - the capability association name
        Returns:
        the capability association, null if not found

      • getCapabilityAssociations

        @Deprecated
public List<CapabilityAssociation> getCapabilityAssociations()
        Deprecated.
        Returns always an empty list since associations are no longer listed.
        List all capability associations in the model.
        Returns:
        all capability associations

      • getCapabilities

        public List<Capability> getCapabilities()
        Get all capabilities in the ontology.
        Returns:
        List of capabilities.

      • searchCapability

        public List<Capability> searchCapability​(String searchTerm,
                                         fi.tut.mei.resdescapi.util.Util.EnumSearchType type)
        Search capability by name.
        Parameters:
        searchTerm - the search term
        type - how to search: capability name starts with, ends with, contains or exactly matches the search term.
        Returns:
        List of capabilities that match the search term.

      • getCombinedCapabilities

        public List<Client.CombinedCapabilityInfo> getCombinedCapabilities​(Collection<Capability> simpleCapabilities)
        Gives combined capabilities that can be formed from some of the given capabilities.
        Parameters:
        simpleCapabilities - capabilities whose combinations are queried
        Returns:
        For each combined capability an object that has the combined capability and those capabilities from the given list that produced it.

      • getBasicResourceInformation

        public ParameterObject getBasicResourceInformation()
        Get basic resource information.
        Returns:
        ParameterObject that represents basic information that can be associated with a device such as mass.

      • getBlueprints

        public List<String> getBlueprints()
        Get the names of all of the device blueprints in the ontology.
        Returns:
        List of blueprint names sorted alphabetically.

      • getIndividualDevices

        public List<String> getIndividualDevices()
        Get the names of all individual devices in the ontology.
        Returns:
        List of individual device names.

      • getBlueprintsByCapability

        public List<String> getBlueprintsByCapability​(Capability capability)
        List names of blueprints that have the given capability.
        Parameters:
        capability - A capability.
        Returns:
        List of blueprint names sorted alphabetically. Null if an internal error happens.

      • getCombinationPossibilitiesForCapability

        public org.apache.jena.ontology.OntModel getCombinationPossibilitiesForCapability​(List<Capability> capabilities,
                                                                                  String fileName,
                                                                                  Predicate<List<String>> filter)
        Find all device combination possibilities that have the given combined capability and can be formed from the device blueprints in the ontology. The combined capabilities and capability parameters of the possibilities will be saved to the returned ontology model which will be saved to the file with the given name.
        Parameters:
        capabilities - Combined capabilities that combinations are created for.
        fileName - Name of the file where the possibilities ontology will be saved. If null ontology will not be saved to a file.
        filter - Allows additional filtering of the created device combinations A filtering function that takes a list of URIs of devices that can be used to form a combination for the capability and returns true if they should form a device combination or false if not. If null no filtering is performed.
        Returns:
        Ontology model containing the created combination possibilities and combined capabilities with parameters.

      • getCombinationPossibilitiesForCapability

        public org.apache.jena.ontology.OntModel getCombinationPossibilitiesForCapability​(Capability capability)
        Find all device combination possibilities that have the given combined capability and can be formed from the device blueprints in the ontology. The combined capabilities and capability parameters of the possibilities will be saved to the returned ontology model.
        Parameters:
        capability - Combined capability that combinations are created for.
        Returns:
        Ontology model containing the created combination possibilities and combined capabilities with parameters.

      • getDeviceCombinationsByCapability

        public List<String> getDeviceCombinationsByCapability​(Capability capability)
        Get names of device combinations that have a given capability. Note this requires that the source ontology contains combined capabilities for device combinations. The method saveAllDeviceCombinations(String, OntModel) can be used to create such an ontology file.
        Parameters:
        capability - the capability
        Returns:
        List of device combination names. Null if there is an error.

      • getIndividualDevicesByCapability

        public List<String> getIndividualDevicesByCapability​(Capability capability)
        Get list of names of individual devices that have the given capability.
        Parameters:
        capability - capability
        Returns:
        List of device names. Null in case of an internal error.

      • getBlueprint

        public Blueprint getBlueprint​(String name)
        Get information about the given blueprint. The information includes capabilities and their parameters.
        Parameters:
        name - Name of a blueprint.
        Returns:
        The blueprint or null if not found or an error was encountered.

      • getIndividualDevice

        public IndividualDevice getIndividualDevice​(String name)
        Get information about the individual device with the given name.
        Parameters:
        name - the device name
        Returns:
        The individual device or null if not found or an error occurs.

      • getDevicesForBlueprint

        public List<String> getDevicesForBlueprint​(String name)
        Get list of names of individual devices that are based on the given blueprint.
        Parameters:
        name - The name of a blueprint.
        Returns:
        List of device names. Null if no blueprint with given name or an internal error.

      • getDeviceCombinations

        public List<String> getDeviceCombinations()
        Get names of all device combinations in the ontology.
        Returns:
        list of device combination names

      • getHighestLevelDeviceCombinations

        public List<String> getHighestLevelDeviceCombinations()
        Get the names of all highest level device combinations. These device combinations are not a part of any other device combination.
        Returns:
        List of device combination names or null in case of an error.

      • individualOfClass

        public boolean individualOfClass​(String individualURI,
                                 String classURI)
        Checks if the ontology has the given individual that belongs to the given class.
        Parameters:
        individualURI - the URI of the individual
        classURI - the URI of the ontology class
        Returns:
        True if the individual and class exist and the individual belongs to the class. False otherwise.

      • executeQuery

        public org.apache.jena.query.ResultSet executeQuery​(String file)
                                             throws IOException,
                                                    org.apache.jena.query.QueryParseException
        Execute the SPARQL query in the given file for the ontology.
        Parameters:
        file - The path to the file containing a SPARQL query
        Returns:
        The query results.
        Throws:
        IOException - If there is a problem in opening the file.
        org.apache.jena.query.QueryParseException - If the SPARQL query is invalid.

      • loadTemplate

        public org.apache.jena.query.QueryExecution loadTemplate​(String name,
                                                         Map<String,​Object> params,
                                                         boolean usePellet)
                                                  throws IOException
        gets a query execution that is based on a sparql query in a file.
        Parameters:
        name - the name of the query template
        params - IRI parameters used to replace variables in the template with actual values. Represents resources in the ontology.
        usePellet - true use pellet to execute query, false use Jena (no reasoning in query)
        Returns:
        query execution ready for execution
        Throws:
        IOException - if template file is not found

      • loadTemplate

        public org.apache.jena.query.QueryExecution loadTemplate​(String name,
                                                         Map<String,​Object> params,
                                                         Map<String,​Object> litParams,
                                                         boolean usePellet)
                                                  throws IOException
        gets a query execution that is based on a sparql query in a file.
        Parameters:
        name - the name of the query template file
        params - IRI parameters used to replace variables in the template with actual values. Represents resources in the ontology.
        litParams - parameters that are literals e.g. strings, numbers
        usePellet - true use pellet to execute query, false use Jena (no reasoning in query)
        Returns:
        query execution ready for execution
        Throws:
        IOException - if template file is not found

      • getOntology

        public org.apache.jena.ontology.OntModel getOntology()
        Returns the Jena ontology model used by the client. Can be used when the user wants to work directly with the ontology for example when the client doesn't offer information required by the user.
        Returns:
        the ontology

      • getDefaultNameSpace

        public String getDefaultNameSpace()
        Get the default name space of the ontology i.e. the one with an empty prefix
        Returns:
        The default name space URI

      • getOntologyURI

        public String getOntologyURI()
        Get the URI of the ontology resource defined in the loaded ontology file.
        Returns:
        The URI of the ontology resource. Null if not found e.g. there is no ontology resource defined in the ontology.