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}