001/**
002 * Copyright (C) 2007 - 2016, Jens Lehmann
003 * <p>
004 * This file is part of DL-Learner.
005 * <p>
006 * DL-Learner is free software; you can redistribute it and/or modify
007 * it under the terms of the GNU General Public License as published by
008 * the Free Software Foundation; either version 3 of the License, or
009 * (at your option) any later version.
010 * <p>
011 * DL-Learner is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014 * GNU General Public License for more details.
015 * <p>
016 * You should have received a copy of the GNU General Public License
017 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
018 */
019package org.dllearner.kb.sparql;
020
021import org.apache.jena.rdf.model.Model;
022
023import java.util.Set;
024
025/**
026 * According to the definition at http://www.w3.org/Submission/CBD/
027 * <p>
028 * <p>...a concise bounded description of a resource in terms of
029 * an RDF graph, as a general and broadly optimal unit of specific knowledge
030 * about that resource to be utilized by, and/or interchanged between, semantic
031 * web agents.
032 * </p>
033 * <p>
034 * <p>
035 * Given a particular node in a particular RDF graph, a <em>concise bounded
036 * description</em> is a subgraph consisting of those statements which together
037 * constitute a focused body of knowledge about the resource denoted by that
038 * particular node. The precise nature of that subgraph will hopefully become
039 * clear given the definition, discussion and example provided below.
040 * </p>
041 * <p>
042 * <p>
043 * Optimality is, of course, application dependent and it is not presumed that a
044 * concise bounded description is an optimal form of description for every
045 * application; however, it is presented herein as a reasonably general and
046 * broadly optimal form of description for many applications, and unless
047 * otherwise warranted, constitutes a reasonable default response to the request
048 * "tell me about this resource".
049 * </p>
050 *
051 * @author Lorenz Buehmann
052 */
053public interface ConciseBoundedDescriptionGenerator {
054
055    String TP = "%s %s %s .\n";
056    default String triplePattern(String s, String p, String o) {
057        return String.format(TP, s, p, o);
058    }
059
060    /**
061     * Computes the CBD (of depth 1) for the given resource.
062     *
063     * @param resource the resource URI
064     * @return the CBD
065     */
066    default Model getConciseBoundedDescription(String resource) {
067        return getConciseBoundedDescription(resource, 1);
068    }
069
070    /**
071     * Computes the CBD of given depth for the given resource.
072     *
073     * @param resource the resource URI
074     * @param depth    the max. depth of the CBD
075     * @return the CBD
076     */
077    default Model getConciseBoundedDescription(String resource, int depth) {
078        return getConciseBoundedDescription(resource, depth, false);
079    }
080
081    /**
082     * Computes the CBD of given depth for the given resource. Optionally, additional
083     * information about the types for the leaf nodes is retrieved.
084     *
085     * @param resource          the resource URI
086     * @param depth             the max. depth of the CBD
087     * @param withTypesForLeafs whether to get the types of the leaf nodes
088     * @return the CBD
089     */
090    Model getConciseBoundedDescription(String resource, int depth, boolean withTypesForLeafs);
091
092    /**
093     * Computes the CBDs (of given depth 1) for the given resources and puts them into a single model.
094     *
095     * @param resources the resource URIs
096     * @return the CBDs in a single model
097     */
098    default Model getConciseBoundedDescription(Set<String> resources) {
099        return getConciseBoundedDescription(resources, 1);
100    }
101
102    /**
103     * Computes the CBDs of given depth for the given resources and puts them into a single model.
104     *
105     * @param resources the resource URIs
106     * @param depth     the max. depth of the CBDs
107     * @return the CBDs in a single model
108     */
109    default Model getConciseBoundedDescription(Set<String> resources, int depth) {
110        return getConciseBoundedDescription(resources, depth, false);
111    }
112
113    /**
114     * Computes the CBD of given depth for the given resources and puts them into a single model. Optionally, additional
115     * information about the types for the leaf nodes is retrieved.
116     *
117     * @param resources         the resource URIs
118     * @param depth             the max. depth of the CBDs
119     * @param withTypesForLeafs whether to get the types of the leaf nodes
120     *
121     * @return the CBDs in a single model
122     */
123    default Model getConciseBoundedDescription(Set<String> resources, int depth, boolean withTypesForLeafs) {
124        return resources.stream()
125                .map(r -> getConciseBoundedDescription(r, depth, withTypesForLeafs))
126                .reduce(Model::union)
127                .orElseThrow(() -> new RuntimeException("Failed to compute CBD for resources " + resources));
128
129    }
130
131
132    /**
133     * Set the property namespaces allowed to occur in triples of the generated CBD. Filtering can happen either remotely
134     * via SPARQL queries or might be implemented locally via post-processing on the retrieved triples.
135     *
136     * @param namespaces the allowed property namespaces
137     */
138    void setAllowedPropertyNamespaces(Set<String> namespaces);
139
140    /**
141     * Set the allowed namespaces for resources occuring in object position of the retrieved triples.
142     * Filtering can happen either remotely via SPARQL queries or might be implemented locally via post-processing
143     * on the retrieved triples.
144     *
145     * @param namespaces the allowed namespaces
146     */
147    void setAllowedObjectNamespaces(Set<String> namespaces);
148
149    /**
150     * Set the allowed namespaces for classes occuring in object position of the retrieved triples.
151     * Filtering can happen either remotely via SPARQL queries or might be implemented locally via post-processing
152     * on the retrieved triples.
153     *
154     * @param namespaces the allowed namespaces
155     */
156    default void setAllowedClassNamespaces(Set<String> namespaces){
157        throw new UnsupportedOperationException("Method not implemented for class " + this.getClass());
158    };
159
160    /**
161     * Set the properties allowed to occur in triples of the generated CBD. Filtering can happen either remotely
162     * via SPARQL queries or might be implemented locally via post-processing on the retrieved triples.
163     *
164     * @param properties the ignored properties
165     */
166    void setIgnoredProperties(Set<String> properties);
167
168
169}