001/* 002 * (C) Copyright 2006-2007 Nuxeo SAS (http://nuxeo.com/) and contributors. 003 * 004 * All rights reserved. This program and the accompanying materials 005 * are made available under the terms of the GNU Lesser General Public License 006 * (LGPL) version 2.1 which accompanies this distribution, and is available at 007 * http://www.gnu.org/licenses/lgpl.html 008 * 009 * This library is distributed in the hope that it will be useful, 010 * but WITHOUT ANY WARRANTY; without even the implied warranty of 011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 012 * Lesser General Public License for more details. 013 * 014 * Contributors: 015 * Nuxeo - initial API and implementation 016 * 017 * $Id: Graph.java 25079 2007-09-18 14:49:05Z atchertchian $ 018 */ 019 020package org.nuxeo.ecm.platform.relations.api; 021 022import java.io.InputStream; 023import java.io.OutputStream; 024import java.io.Serializable; 025import java.util.List; 026import java.util.Map; 027 028/** 029 * Interface for graphs. 030 * <p> 031 * New types of graphs will be registered using extension points. 032 * <p> 033 * Graphs have to be serializable has they will be kept as references in the RelationService bean. 034 * 035 * @author <a href="mailto:at@nuxeo.com">Anahide Tchertchian</a> 036 */ 037public interface Graph extends Serializable { 038 039 /** 040 * Sets the graph description. 041 * 042 * @param graphDescription 043 */ 044 void setDescription(GraphDescription graphDescription); 045 046 /** 047 * Returns namespaces for the graph. 048 * <p> 049 * Namespaces are prefix/namespace bindings, as rdf for http://www.w3.org/1999/02/22-rdf-syntax-ns#. 050 * 051 * @returns namespaces map of namespace bindings for the graph 052 */ 053 Map<String, String> getNamespaces(); 054 055 /** 056 * Adds the statement object to the graph. 057 * 058 * @param statement statement to add 059 * @since 5.5 060 */ 061 void add(Statement statement); 062 063 /** 064 * Adds given list of Statement objects to the graph. 065 * 066 * @param statements list of Statement instances to add 067 */ 068 void add(List<Statement> statements); 069 070 /** 071 * Removes the statement object from the graph. 072 * 073 * @param statement statement to remove 074 * @since 5.5 075 */ 076 void remove(Statement statement); 077 078 /** 079 * Removes given list of Statement objects from the graph. 080 * 081 * @param statements List of Statement instances to remove 082 */ 083 void remove(List<Statement> statements); 084 085 /** 086 * Returns all statements in the graph. 087 * 088 * @return list of Statement instances 089 */ 090 List<Statement> getStatements(); 091 092 /** 093 * Returns all statements in the graph matching the pattern. 094 * 095 * @param statement pattern to match, can hold null nodes as wildcards 096 * @return list of Statement instances matching the pattern 097 */ 098 List<Statement> getStatements(Statement statement); 099 100 /** 101 * Returns all statements in the graph matching the pattern. 102 * 103 * @param statement pattern to match, can hold null nodes as wildcards 104 * @return list of Statement instances matching the pattern 105 * @since 5.5 106 */ 107 List<Statement> getStatements(Node subject, Node predicate, Node object); 108 109 /** 110 * Get items matching the statement pattern (null, predicate, object). 111 * 112 * @param predicate predicate pattern, null accepted 113 * @param object object pattern, null accepted 114 * @return list of subjects 115 */ 116 List<Node> getSubjects(Node predicate, Node object); 117 118 /** 119 * Gets items matching the statement pattern (subject, null, object). 120 * 121 * @param subject subject pattern, null accepted 122 * @param object object pattern, null accepted 123 * @return list of predicates 124 */ 125 List<Node> getPredicates(Node subject, Node object); 126 127 /** 128 * Gets items matching the statement pattern (subject, predicate, null). 129 * 130 * @param subject subject pattern, null accepted 131 * @param predicate predicate pattern, null accepted 132 * @return list of node objects 133 */ 134 List<Node> getObjects(Node subject, Node predicate); 135 136 /** 137 * Returns true if given statement pattern is in the graph. 138 * 139 * @param statement statement pattern, can use null as wild cards 140 * @return true or false 141 */ 142 boolean hasStatement(Statement statement); 143 144 /** 145 * Returns true if given resource appears in any statement of the graph. 146 * 147 * @param resource 148 * @return true or false 149 */ 150 boolean hasResource(Resource resource); 151 152 /** 153 * Returns the number of statements in the graph. 154 * 155 * @return number of statements as a Long 156 */ 157 Long size(); 158 159 /** 160 * Clears the graph, removing all statements in it. 161 */ 162 void clear(); 163 164 /** 165 * Query the graph using a base URI. 166 * 167 * @param queryString the query string 168 * @param language the query language (sparql, rdql,...) 169 * @param baseURI the base URI to use for query 170 * @return QueryResult instance 171 */ 172 QueryResult query(String queryString, String language, String baseURI); 173 174 /** 175 * Counts the number of results of a query. 176 * 177 * @param queryString the query string 178 * @param language the query language (sparql, rdql,...) 179 * @param baseURI the base URI to use for query 180 * @return the count 181 */ 182 int queryCount(String queryString, String language, String baseURI); 183 184 // I/O 185 186 /** 187 * Parses source into the graph. 188 * 189 * @param path path on file system where to take the serialization file 190 * @param lang format for the input serialization, may be "RDF/XML", "RDF/XML-ABBREV", "N-TRIPLE" and "N3". The 191 * default value, represented by null, is "RDF/XML". 192 * @param base base uri to be used when converting relative uris to absolute uris, may be null. If set to "", allows 193 * relative uris to be used in the model. 194 * @return true on success, else false 195 */ 196 boolean read(String path, String lang, String base); 197 198 /** 199 * Parses source into the graph. 200 * 201 * @param in input stream 202 * @param lang format for the input serialization, may be "RDF/XML", "RDF/XML-ABBREV", "N-TRIPLE" and "N3". The 203 * default value, represented by null, is "RDF/XML". 204 * @param base base uri to be used when converting relative uris to absolute uris, may be null. If set to "", allows 205 * relative uris to be used in the model. 206 * @return true on success, else false 207 */ 208 boolean read(InputStream in, String lang, String base); 209 210 /** 211 * Serializes graph. 212 * 213 * @param path path on file system where to put the serialization file 214 * @param lang format for the input serialization, may be "RDF/XML", "RDF/XML-ABBREV", "N-TRIPLE" and "N3". The 215 * default value, represented by null, is "RDF/XML". 216 * @param base base uri to be used when converting relative uris to absolute uris, may be null. If set to "", allows 217 * relative uris to be used in the model. 218 * @return true on success, else false 219 */ 220 boolean write(String path, String lang, String base); 221 222 /** 223 * Serializes graph. 224 * 225 * @param out output stream 226 * @param lang format for the input serialization, may be "RDF/XML", "RDF/XML-ABBREV", "N-TRIPLE" and "N3". The 227 * default value, represented by null, is "RDF/XML". 228 * @param base base uri to be used when converting relative uris to absolute uris, may be null. If set to "", allows 229 * relative uris to be used in the model. 230 * @return true on success, else false 231 */ 232 boolean write(OutputStream out, String lang, String base); 233 234}