Update ooo320-m1
[ooovba.git] / offapi / com / sun / star / rdf / XDocumentRepository.idl
blobd9131291d81aa8aea0905806d0a3d0abbf2af6e8
1 /*************************************************************************
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5 * Copyright 2008 by Sun Microsystems, Inc.
7 * OpenOffice.org - a multi-platform office productivity suite
9 * $RCSfile: XDocumentRepository.idl,v $
10 * $Revision: 1.2 $
12 * This file is part of OpenOffice.org.
14 * OpenOffice.org is free software: you can redistribute it and/or modify
15 * it under the terms of the GNU Lesser General Public License version 3
16 * only, as published by the Free Software Foundation.
18 * OpenOffice.org is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU Lesser General Public License version 3 for more details
22 * (a copy is included in the LICENSE file that accompanied this code).
24 * You should have received a copy of the GNU Lesser General Public License
25 * version 3 along with OpenOffice.org. If not, see
26 * <http://www.openoffice.org/license.html>
27 * for a copy of the LGPLv3 License.
29 ************************************************************************/
31 #ifndef __com_sun_star_rdf_XDocumentRepository_idl__
32 #define __com_sun_star_rdf_XDocumentRepository_idl__
34 #ifndef __com_sun_star_rdf_XMetadatable_idl__
35 #include <com/sun/star/rdf/XMetadatable.idl>
36 #endif
38 #ifndef __com_sun_star_rdf_XRepository_idl__
39 #include <com/sun/star/rdf/XRepository.idl>
40 #endif
43 //=============================================================================
45 module com { module sun { module star { module rdf {
47 //=============================================================================
48 /** extends <type>XRepository</type> with document-specific functionality.
50 <p>
51 This subclass of <type>XRepository</type> provides some methods which
52 only make sense for repositories that are attached to a document.
53 For example, the methods allow for manipulating in-content metadata,
54 which is stored as RDFa.
55 </p>
57 @since OOo 3.2
59 @see XRepositorySupplier
60 @see XDocumentMetadataAccess
62 interface XDocumentRepository : XRepository
65 //-------------------------------------------------------------------------
66 /** update the RDFa statement(s) that correspond to an ODF element in the
67 repository.
69 <p>
70 This method will do the following steps:
71 <ol>
72 <li>Remove all previously set RDFa statements for the Object parameter
73 from the repository</li>
74 <li>If the RDFaContent parameter is the empty <atom>string</atom>,
75 for every Predicate in the given list of Predicates,
76 add the following RDF statement to an unspecified named graph:
77 <ul>
78 <li><code>Subject Predicate
79 XLiteral(Object->getText()^^RDFaDatatype)</code></li>
80 </ul>
81 </li>
82 <li>If the RDFaContent parameter is not the empty <atom>string</atom>,
83 for every Predicate in the given list of Predicates,
84 add the following RDF statement to an unspecified named graph:
85 <ul>
86 <li>
87 <code>Subject Predicate XLiteral(RDFaContent^^RDFaDatatype)</code>
88 </li>
89 </ul>
90 Further, add the following RDF statement to the same unspecified
91 named graph:
92 <ul>
93 <li>
94 <code>Subject rdfs:label XLiteral(Object->getText())</code>
95 </li>
96 </ul>
97 </li>
98 </ol>
99 </p>
102 RDFa statements are handled specially because they are not logically
103 part of any named graph in the repository.
104 Also, they have rather unusual semantics;
105 just using <member>XNamedGraph::addStatement</member> would be
106 ambiguous:
107 if the object is a <type>XMetadatable</type>, do we insert
108 the object itself (URI) or its literal content (RDFa)?
109 </p>
111 @param Subject
112 the subject of the RDF triple(s).
114 @param Predicates
115 the predicates of the RDF triple(s).
117 @param Object
118 the object of the RDF triple(s) is the text content of this
119 parameter.
121 @param RDFaContent
122 the <code>rdfa:content</code> attribute (may be the empty
123 <atom>string</atom>).
125 @param RDFaDatatype
126 the <code>rdfa:datatype</code> attribute (may be <NULL/>)
128 @throws com::sun::star::lang::IllegalArgumentException
129 if any parameter is <NULL/>, Predicates is empty,
130 or Object is of a type that can not have RDFa metadata attached.
132 @throws RepositoryException
133 if an error occurs when accessing the repository.
135 void setStatementRDFa(
136 [in] XResource Subject,
137 [in] sequence<XURI> Predicates,
138 [in] XMetadatable Object,
139 [in] string RDFaContent,
140 [in] XURI RDFaDatatype)
141 raises( com::sun::star::lang::IllegalArgumentException,
142 RepositoryException );
144 //-------------------------------------------------------------------------
145 /** remove the RDFa statement(s) that correspond to an ODF element from the
146 repository.
149 RDFa statements are handled specially because they are not logically
150 part of any graph.
151 </p>
153 @param Element
154 the element whose RDFa statement(s) should be removed
156 @throws com::sun::star::lang::IllegalArgumentException
157 if the given Element is <NULL/>, or of a type that can not have
158 RDFa metadata attached.
160 @throws RepositoryException
161 if an error occurs when accessing the repository.
163 void removeStatementRDFa([in] XMetadatable Element)
164 raises( com::sun::star::lang::IllegalArgumentException,
165 RepositoryException );
167 //-------------------------------------------------------------------------
168 /** find the RDFa statement(s) associated with an ODF element.
170 @param Element
171 the ODF element for which RDFa statements should be found
173 @returns
174 <ul>
175 <li>if the element has no RDFa meta-data attributes:
176 the empty sequence.</li>
177 <li>if the element has RDFa meta-data attributes:
178 and no <code>rdfa:content</code> attached:
179 a sequence with the RDFa-statements corresponding to the
180 attributes</li>
181 <li>if the element has RDFa meta-data attributes,
182 and also <code>rdfa:content</code> attached:
183 a sequence with the RDFa-statements corresponding to the
184 attributes, including the RDFa-labels-statement</li>
185 </ul>
187 @throws com::sun::star::lang::IllegalArgumentException
188 if the given Element is <NULL/>, or of a type that can not have
189 RDFa metadata attached.
191 @throws RepositoryException
192 if an error occurs when accessing the repository.
194 @see Statement
196 sequence<Statement> getStatementRDFa([in] XMetadatable Element)
197 raises( com::sun::star::lang::IllegalArgumentException,
198 RepositoryException );
200 //-------------------------------------------------------------------------
201 /** gets matching RDFa statements from the repository.
204 This method exists because RDFa statements are not part of any named
205 graph, and thus they cannot be enumerated with
206 <member>XNamedGraph::getStatements</member>.
207 </p>
210 Any parameter may be <NULL/>, which acts as a wildcard.
211 For example, to get all statements about myURI:
212 <code>getStatementsRDFa(myURI, null, null)</code>
213 </p>
215 @param Subject
216 the subject of the RDF triple.
218 @param Predicate
219 the predicate of the RDF triple.
221 @param Object
222 the object of the RDF triple.
224 @returns
225 an iterator over all RDFa statements in the repository that match
226 the parameters, represented as an
227 enumeration of <type>Statement</type>
229 @throws RepositoryException
230 if an error occurs when accessing the repository.
232 @see Statement
233 @see XRepository::getStatements
234 @see XNamedGraph::getStatements
236 com::sun::star::container::XEnumeration/*<Statement>*/ getStatementsRDFa(
237 [in] XResource Subject,
238 [in] XURI Predicate,
239 [in] XNode Object)
240 raises( RepositoryException );
244 //=============================================================================
246 }; }; }; };
248 #endif