org.semanticweb.owlapi.reasoner.Node Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of owlapi-api Show documentation
The newest version!
/*
 * This file is part of the OWL API.
 *
 * The contents of this file are subject to the LGPL License, Version 3.0.
 *
 * Copyright (C) 2011, The University of Manchester
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see http://www.gnu.org/licenses/.
 *
 *
 * Alternatively, the contents of this file may be used under the terms of the Apache License, Version 2.0
 * in which case, the provisions of the Apache License Version 2.0 are applicable instead of those above.
 *
 * Copyright 2011, University of Manchester
 *
 * 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
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * 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 org.semanticweb.owlapi.reasoner;

import java.util.Set;

import org.semanticweb.owlapi.model.OWLObject;

/**
 * Author: Matthew Horridge

 * The University of Manchester

 * Information Management Group

 * Date: 03-Jul-2009
 * 
 *
 * Represents a node (set) of entities.  The entities in a node are equivalent to each other.
 * 
 *
 * Nodes in hierarchies
 * In the OWL API, a reasoner treats a class hierarchy, an object property hierarchy or a data property hierarchy
 * as a hierarchy (directed acyclic graph - DAG) of Nodes.  Each node contains entities that are equivalent
 * to each other.  A hierarchy contains a top node, which is the ancestor of all nodes in the hierarchy, and
 * a bottom node which is the descendant of all nodes in the hierarchy.
 * 
 * In a class hierarchy, the nodes contain OWLClass objects.  The top node contains owl:Thing (and
 * any other named classes that are equivalent to owl:Thing).
 * The bottom node contains owl:Nothing
 * (and any other named classes that are equivalent to owl:Nothing - these classes are unsatisfiable
 * classes).
 * 
 * In an object property hierarchy, the nodes contain OWLObjectProperty objects.  The top node contains
 * owl:topObjectProperty (and any other named object properties that are equivalent to owl:topObjectProperty).
 * The bottom node contains owl:bottomObjectProperty
 * (and any other named object properties that are equivalent to owl:bottomObjectProperty).
 * 
 * In a data property hierarchy, the nodes contain OWLDataProperty objects.  The top node contains
 * owl:topDataProperty (and any other data properties that are equivalent to owl:topDataProperty).
 * The bottom node contains owl:bottomDataProperty
 * (and any other data properties that are equivalent to owl:bottomDataProperty).
 *
 * Class Hierarchy Example
 * The figure below shows an example class hierarchy.  Each box in the hierarchy represents a Node.  In
 * this case the top node contains owl:Thing and the bottom node contains owl:Nothing
 * because the nodes in the hierarchy are OWLClass nodes.  In this case, class G
 * is equivalent to owl:Thing so it appears as an entity in the top node. Similarly, class K
 * is unsatisfiable, so it is equivalent to owl:Nothing and therefore appears in the bottom node containing
 * owl:Nothing.
 * 
 *
 * 
 *  
 * 
 *
 * @param  the type of elements represented in the Node
 */
public interface Node extends Iterable {

    /**
     * Determines if this node represents the top node (in a hierarchy).
     * For a named class node,
     * the top node is the node that contains owl:Thing. For an object property node, the top node
     * is the node that contains owl:topObjectProperty.  For a data property node, the top node is the
     * node that contains owl:topDataProperty
     * @return
     * true if this node is an OWLClass node and it contains owl:Thing.
     * 
     * true if this node is an OWLObjectProperty node and it contains owl:topObjectProperty.
     * 
     * true if this node is an OWLDataProperty node and it contains owl:topDataProperty.
     * 
     * false if none of the above.
     */
    boolean isTopNode();

    /**
     * Determines if this node represents the bottom node (in a hierarchy).
     * For a named class node,
     * the bottom node is the node that contains owl:Nothing. For an object property node, the bottom node
     * is the node that contains owl:bottomObjectProperty.  For a data property node, the bottom node is the
     * node that contains owl:bottomDataProperty
     * @return
     * true if this node is an OWLClass node and it contains owl:Nothing.
     * 
     * true if this node is an OWLObjectProperty node and it contains owl:bottomObjectProperty.
     * 
     * true if this node is an OWLDataProperty node and it contains owl:bottomDataProperty.
     * 
     * false if none of the above.
     */
    boolean isBottomNode();

    /**
     * Gets the entities contained in this node.  The entities are equivalent to each other.
     * @return The set of entities contained in this Node.
     */
    Set getEntities();

    /**
     * Gets the number of entities contained in this Node
     * @return The number of entities contained in this node.
     */
    int getSize();

    /**
     * Determines if this node contains the specified entity.
     * @param entity The entity to check for
     * @return true if this node contains entity, or false if this node
     * does not contain entity
     */
    boolean contains(E entity);

    /**
     * Gets the entities contained in this node minus the specified entitie e.  This essentially
     * returns the entities that are returned by {@link #getEntities()} minus the specified entity e
     * @param e The entity that, is contained within this node, but should not be included in the return set.
     * @return The set of entities that are contained in this node minus the specified entity, e. If
     * e is not contained within this node then the full set of entities returned is the same as that
     * returned by {@link #getEntities()}
     */
    Set getEntitiesMinus(E e);

    /**
     * Gets the entities contained in this node minus the top entity.
     * For a node of named classes the top entity is owl:Thing.
     * For a node of object properties the top entity is owl:topObjectProperty.
     * For a node of data properties the top entity is owl:topDataProperty
     * @return The set of entities contained within this node minus the top entity. If this node does not contain
     * the top entity then the set of entities returned is the same as that returned by {@link #getEntities()}.
     */
    Set getEntitiesMinusTop();

    /**
     * Gets the entities contained in this node minus the bottom entity.
     * For a node of named classes the bottom entity is owl:Nothing.
     * For a node of object properties the bottom entity is owl:bottomObjectProperty.
     * For a node of data properties the bottom entity is owl:bottomDataProperty
     * @return The set of entities contained within this node minus the bottom entity. If this node does not contain
     * the bottom entity then the set of entities returned is the same as that returned by {@link #getEntities()}.
     */
    Set getEntitiesMinusBottom();

    /**
     * Determines if this Node contains just one entity.
     * @return true if this Node contains just one entity, otherwise false
     */
    boolean isSingleton();

    /**
     * Gets one of the entities contained in this entity set.  If this is a singleton set it will be the one and
     * only entity.
     * @return An entity from the set of entities contained within this node
     * @throws RuntimeException if this node is empty (it does not contain any entities).
     */
    E getRepresentativeElement();
}