Java tutorial
/** * Copyright (c) 2015 Lemur Consulting Ltd. * <p/> * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * <p/> * http://www.apache.org/licenses/LICENSE-2.0 * <p/> * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package uk.co.flax.biosolr.elasticsearch.mapper.ontology.owl; import java.net.URI; import java.net.URISyntaxException; import java.net.URL; import java.util.ArrayList; import java.util.Collection; import java.util.Collections; import java.util.HashMap; import java.util.HashSet; import java.util.List; import java.util.Map; import java.util.Optional; import java.util.Set; import org.apache.commons.lang3.StringUtils; import org.semanticweb.owlapi.apibinding.OWLManager; import org.semanticweb.owlapi.model.IRI; import org.semanticweb.owlapi.model.OWLAnnotationAssertionAxiom; import org.semanticweb.owlapi.model.OWLAnnotationProperty; import org.semanticweb.owlapi.model.OWLAnnotationValue; import org.semanticweb.owlapi.model.OWLClass; import org.semanticweb.owlapi.model.OWLClassExpression; import org.semanticweb.owlapi.model.OWLDataFactory; import org.semanticweb.owlapi.model.OWLLiteral; import org.semanticweb.owlapi.model.OWLObjectProperty; import org.semanticweb.owlapi.model.OWLObjectSomeValuesFrom; import org.semanticweb.owlapi.model.OWLOntology; import org.semanticweb.owlapi.model.OWLOntologyCreationException; import org.semanticweb.owlapi.model.OWLOntologyManager; import org.semanticweb.owlapi.model.OWLSubClassOfAxiom; import org.semanticweb.owlapi.reasoner.Node; import org.semanticweb.owlapi.reasoner.NodeSet; import org.semanticweb.owlapi.reasoner.OWLReasoner; import org.semanticweb.owlapi.reasoner.structural.StructuralReasonerFactory; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import uk.co.flax.biosolr.elasticsearch.mapper.ontology.OntologySettings; /** * Helper class for loading an ontology and making its properties easily * accessible. * * @author mlp */ public class OntologyHelper { private static final Logger LOGGER = LoggerFactory.getLogger(OntologyHelper.class); private final OntologySettings config; private final URI ontologyUri; private final OWLOntology ontology; private final OWLReasoner reasoner; // private final ShortFormProvider shortFormProvider; private final IRI owlNothingIRI; private final Map<IRI, OWLClass> owlClassMap = new HashMap<>(); private Map<IRI, Collection<String>> labels = new HashMap<>(); private Map<IRI, Collection<String>> synonyms = new HashMap<>(); private Map<IRI, Collection<String>> definitions = new HashMap<>(); private long lastCallTime; /** * Construct a new ontology helper instance with a string representing the * ontology URI. * * @param ontologyUriString the URI. * @param config the ontology configuration, containing the property URIs * for labels, synonyms, etc. * @throws OWLOntologyCreationException if the ontology cannot be read for * some reason - internal inconsistencies, etc. * @throws URISyntaxException if the URI cannot be parsed. */ public OntologyHelper(OntologySettings config) throws OWLOntologyCreationException, URISyntaxException { this(new URI(config.getOntologyUri()), config); } /** * Construct a new ontology helper instance. * * @param ontologyUri the URI giving the location of the ontology. * @param config the ontology configuration, containing the property URIs * for labels, synonyms, etc. * @throws OWLOntologyCreationException if the ontology cannot be read for * some reason - internal inconsistencies, etc. * @throws URISyntaxException if the URI cannot be parsed. */ public OntologyHelper(URI ontologyUri, OntologySettings config) throws OWLOntologyCreationException, URISyntaxException { this.config = config; if (!ontologyUri.isAbsolute()) { // Try to read as a file from the resource path LOGGER.debug("Ontology URI {} is not absolute - loading from classpath", ontologyUri); URL url = this.getClass().getClassLoader().getResource(ontologyUri.toString()); if (url != null) { ontologyUri = url.toURI(); } } this.ontologyUri = ontologyUri; LOGGER.info("Loading ontology from " + ontologyUri + "..."); OWLOntologyManager manager = OWLManager.createOWLOntologyManager(); IRI iri = IRI.create(ontologyUri); this.ontology = manager.loadOntologyFromOntologyDocument(iri); // Use a buffering reasoner - not interested in ongoing changes this.reasoner = new StructuralReasonerFactory().createReasoner(ontology); // this.shortFormProvider = new SimpleShortFormProvider(); this.owlNothingIRI = manager.getOWLDataFactory().getOWLNothing().getIRI(); // Initialise the class map initialiseClassMap(); } private void initialiseClassMap() { for (OWLClass clazz : ontology.getClassesInSignature()) { owlClassMap.put(clazz.getIRI(), clazz); } } /** * Explicitly dispose of the helper class, closing down any resources in * use. */ public void dispose() { if (reasoner != null) { LOGGER.info("Disposing of ontology reasoner for {}", ontologyUri); reasoner.dispose(); } } /** * Get the OWL class for an IRI. * * @param iri the IRI of the required class. * @return the class from the ontology, or <code>null</code> if no such * class can be found, or the IRI string is null. */ public OWLClass getOwlClass(String iri) { OWLClass ret = null; if (StringUtils.isNotBlank(iri)) { ret = owlClassMap.get(IRI.create(iri)); } return ret; } /** * Find the labels for a single OWL class. * * @param owlClass the class whose labels are required. * @return a collection of labels for the class. Never <code>null</code>. */ public Collection<String> findLabels(OWLClass owlClass) { return findLabels(owlClass.getIRI()); } /** * Find all of the labels for a collection of OWL class IRIs. * * @param iris the IRIs whose labels should be looked up. * @return a collection of labels. Never <code>null</code>. */ public Collection<String> findLabelsForIRIs(Collection<String> iris) { Set<String> labels = new HashSet<>(); iris.stream().map(iri -> findLabels(IRI.create(iri))).forEach(labels::addAll); return labels; } /** * Find all of the synonyms for an OWL class. * * @param owlClass * @return the synonyms. Never <code>null</code>. */ public Collection<String> findSynonyms(OWLClass owlClass) { return findSynonyms(owlClass.getIRI()); } /** * Find all of the definitions for an OWL class. * * @param owlClass * @return the definitions. Never <code>null</code>. */ public Collection<String> findDefinitions(OWLClass owlClass) { return findDefinitions(owlClass.getIRI()); } private Collection<String> findLabels(IRI iri) { if (!labels.containsKey(iri)) { Collection<String> classNames = findPropertyValueStrings(config.getLabelPropertyUris(), iri); labels.put(iri, classNames); } return labels.get(iri); } private Collection<String> findSynonyms(IRI iri) { if (!synonyms.containsKey(iri)) { Collection<String> classNames = findPropertyValueStrings(config.getSynonymPropertyUris(), iri); synonyms.put(iri, classNames); } return synonyms.get(iri); } private Collection<String> findDefinitions(IRI iri) { if (!definitions.containsKey(iri)) { Collection<String> classNames = findPropertyValueStrings(config.getDefinitionPropertyUris(), iri); definitions.put(iri, classNames); } return definitions.get(iri); } private Collection<String> findPropertyValueStrings(List<String> propertyUris, IRI iri) { Collection<String> classNames = new HashSet<>(); OWLDataFactory odf = ontology.getOWLOntologyManager().getOWLDataFactory(); // For every property URI, find the annotations for this entry propertyUris.parallelStream().map(uri -> odf.getOWLAnnotationProperty(IRI.create(uri))) .map(prop -> findAnnotationNames(iri, prop)).forEach(classNames::addAll); return classNames; } private Collection<String> findAnnotationNames(IRI iri, OWLAnnotationProperty annotationType) { Collection<String> classNames = new HashSet<String>(); // get all literal annotations for (OWLAnnotationAssertionAxiom axiom : ontology.getAnnotationAssertionAxioms(iri)) { if (axiom.getAnnotation().getProperty().equals(annotationType)) { OWLAnnotationValue value = axiom.getAnnotation().getValue(); Optional<String> name = getOWLAnnotationValueAsString(value); if (name.isPresent()) { classNames.add(name.get()); } } } return classNames; } /** * Get the direct child URIs for an OWL class. * * @param owlClass * @return the child URIs, as strings. Never <code>null</code>. */ public Collection<String> getChildUris(OWLClass owlClass) { return getSubclassUris(owlClass, true); } /** * Get all descendant URIs for an OWL class, including direct children. * * @param owlClass * @return the descendant URIs, as strings. Never <code>null</code>. */ public Collection<String> getDescendantUris(OWLClass owlClass) { return getSubclassUris(owlClass, false); } /** * Get direct parent URIs for an OWL class. * * @param owlClass * @return the parent URIs, as strings. Never <code>null</code>. */ public Collection<String> getParentUris(OWLClass owlClass) { return getSuperclassUris(owlClass, true); } /** * Get all ancestor URIs for an OWL class, including direct parents. * * @param owlClass * @return the ancestor URIs, as strings. Never <code>null</code>. */ public Collection<String> getAncestorUris(OWLClass owlClass) { return getSuperclassUris(owlClass, false); } private Collection<String> getSubclassUris(OWLClass owlClass, boolean direct) { return getUrisFromNodeSet(reasoner.getSubClasses(owlClass, direct)); } private Collection<String> getSuperclassUris(OWLClass owlClass, boolean direct) { return getUrisFromNodeSet(reasoner.getSuperClasses(owlClass, direct)); } private Collection<String> getUrisFromNodeSet(NodeSet<OWLClass> nodeSet) { Set<String> uris = new HashSet<>(); for (Node<OWLClass> node : nodeSet) { for (OWLClass expr : node.getEntities()) { if (isClassSatisfiable(expr)) { uris.add(expr.getIRI().toURI().toString()); } } } return uris; } private boolean isClassSatisfiable(OWLClass owlClass) { return !owlClass.isAnonymous() && !owlClass.getIRI().equals(owlNothingIRI); } /** * Retrieve a map of related classes for a particular class. * * @param owlClass * @return a map of relation type to a list of IRIs for nodes with that * relationship. */ public Map<String, List<String>> getRestrictions(OWLClass owlClass) { RestrictionVisitor visitor = new RestrictionVisitor(Collections.singleton(ontology)); for (OWLSubClassOfAxiom ax : ontology.getSubClassAxiomsForSubClass(owlClass)) { OWLClassExpression superCls = ax.getSuperClass(); // Ask our superclass to accept a visit from the RestrictionVisitor // - if it is an existential restriction then our restriction visitor // will answer it - if not our visitor will ignore it superCls.accept(visitor); } Map<String, List<String>> restrictions = new HashMap<>(); for (OWLObjectSomeValuesFrom val : visitor.getSomeValues()) { OWLClassExpression exp = val.getFiller(); // Get the shortname of the property expression String shortForm = null; Set<OWLObjectProperty> signatureProps = val.getProperty().getObjectPropertiesInSignature(); for (OWLObjectProperty sigProp : signatureProps) { Collection<String> labels = findLabels(sigProp.getIRI()); if (labels.size() > 0) { shortForm = new ArrayList<String>(labels).get(0); } } if (shortForm != null && !exp.isAnonymous()) { IRI iri = exp.asOWLClass().getIRI(); if (!restrictions.containsKey(shortForm)) { restrictions.put(shortForm, new ArrayList<String>()); } restrictions.get(shortForm).add(iri.toString()); } } return restrictions; } private Optional<String> getOWLAnnotationValueAsString(OWLAnnotationValue value) { if (value instanceof IRI) { Optional<String> shortForm = getShortForm((IRI) value); if (shortForm.isPresent()) { return Optional.of(shortForm.get()); } } else if (value instanceof OWLLiteral) { return Optional.of(((OWLLiteral) value).getLiteral()); } return Optional.empty(); } private Optional<String> getShortForm(IRI entityIRI) { LOGGER.trace("Attempting to extract fragment name of URI '" + entityIRI + "'"); String termURI = entityIRI.toString(); URI entUri = entityIRI.toURI(); // we want the "final part" of the URI... if (!StringUtils.isEmpty(entUri.getFragment())) { // a uri with a non-null fragment, so use this... LOGGER.trace("Extracting fragment name using URI fragment (" + entUri.getFragment() + ")"); return Optional.of(entUri.getFragment()); } else if (entityIRI.toURI().getPath() != null) { // no fragment, but there is a path so try and extract the final // part... if (entityIRI.toURI().getPath().contains("/")) { LOGGER.trace("Extracting fragment name using final part of the path of the URI"); return Optional.of( entityIRI.toURI().getPath().substring(entityIRI.toURI().getPath().lastIndexOf('/') + 1)); } else { // no final path part, so just return whole path LOGGER.trace("Extracting fragment name using the path of the URI"); return Optional.of(entityIRI.toURI().getPath()); } } else { // no fragment, path is null, we've run out of rules so don't // shorten LOGGER.trace("No rules to shorten this URI could be found (" + termURI + ")"); return Optional.empty(); } } /** * Update the record of the last time this class was used. This * method should be called every time the helper class is accessed. */ public void updateLastCallTime() { this.lastCallTime = System.currentTimeMillis(); } /** * @return the last time the helper was called. */ public long getLastCallTime() { return lastCallTime; } public Set<String> getRestrictionProperties() { Set<String> properties = new HashSet<>(); Set<OWLObjectProperty> objectProperties = ontology.getObjectPropertiesInSignature(); for (OWLObjectProperty oop : objectProperties) { List<String> labels = new ArrayList<>(findLabels(oop.getIRI())); if (!labels.isEmpty()) { properties.add(labels.get(0)); } else { Optional<String> shortForm = getShortForm(oop.getIRI()); if (shortForm.isPresent()) { properties.add(shortForm.get()); } } } return properties; } }