1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23
24#ifndef __com_sun_star_rdf_XDocumentMetadataAccess_idl__
25#define __com_sun_star_rdf_XDocumentMetadataAccess_idl__
26
27#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
28#include <com/sun/star/lang/IllegalArgumentException.idl>
29#endif
30
31#ifndef __com_sun_star_lang_WrappedTargetException_idl__
32#include <com/sun/star/lang/WrappedTargetException.idl>
33#endif
34
35#ifndef __com_sun_star_beans_PropertyValue_idl__
36#include <com/sun/star/beans/PropertyValue.idl>
37#endif
38
39#ifndef __com_sun_star_container_ElementExistException_idl__
40#include <com/sun/star/container/ElementExistException.idl>
41#endif
42
43#ifndef __com_sun_star_container_NoSuchElementException_idl__
44#include <com/sun/star/container/NoSuchElementException.idl>
45#endif
46
47#ifndef __com_sun_star_io_IOException_idl__
48#include <com/sun/star/io/IOException.idl>
49#endif
50
51#ifndef __com_sun_star_io_XInputStream_idl__
52#include <com/sun/star/io/XInputStream.idl>
53#endif
54
55#ifndef __com_sun_star_datatransfer_UnsupportedFlavorException_idl__
56#include <com/sun/star/datatransfer/UnsupportedFlavorException.idl>
57#endif
58
59#ifndef __com_sun_star_embed_XStorage_idl__
60#include <com/sun/star/embed/XStorage.idl>
61#endif
62
63#ifndef __com_sun_star_task_XInteractionHandler_idl__
64#include <com/sun/star/task/XInteractionHandler.idl>
65#endif
66
67#ifndef __com_sun_star_rdf_FileFormat_idl__
68#include <com/sun/star/rdf/FileFormat.idl>
69#endif
70
71#ifndef __com_sun_star_rdf_ParseException_idl__
72#include <com/sun/star/rdf/ParseException.idl>
73#endif
74
75#ifndef __com_sun_star_rdf_XURI_idl__
76#include <com/sun/star/rdf/XURI.idl>
77#endif
78
79#ifndef __com_sun_star_rdf_XMetadatable_idl__
80#include <com/sun/star/rdf/XMetadatable.idl>
81#endif
82
83#ifndef __com_sun_star_rdf_XRepositorySupplier_idl__
84#include <com/sun/star/rdf/XRepositorySupplier.idl>
85#endif
86
87
88//=============================================================================
89
90module com {   module sun {   module star {   module rdf {
91
92//=============================================================================
93/** document metadata functionality related to the "manifest.rdf".
94
95    <p>
96    This interface contains some methods that create connections between
97    the content and the RDF metadata of an ODF document.
98    The main idea is to make querying and manipulating the
99    data in the metadata manifest easier.
100    </p>
101
102    <p>
103    Note that this interface inherits from <type>XURI</type>: the
104    base URI of the document is the string value of the RDF node.
105    This is so that you can easily make RDF statements about the document.
106    </p>
107
108    @since OpenOffice 3.2
109
110    @see XDocumentRepository
111 */
112interface XDocumentMetadataAccess
113{
114    interface XURI;
115    interface XRepositorySupplier;
116
117    //-------------------------------------------------------------------------
118    /** get the unique ODF element with the given metadata reference.
119
120        @param MetadataReference
121            a metadata reference, comprising the stream name and the XML ID
122            For example: Pair("content.xml", "foo-element-1")
123
124        @returns
125            the ODF element with the given metadata references if it exists,
126            else <NULL/>
127     */
128    XMetadatable getElementByMetadataReference(
129        [in] com::sun::star::beans::StringPair MetadataReference);
130
131    //-------------------------------------------------------------------------
132    /** get the ODF element that corresponds to an URI.
133
134        @param URI
135            an URI that may identify an ODF element
136
137        @returns
138            the ODF element that corresponds to the given URI, or <NULL/>
139
140        @throws com::sun::star::lang::IllegalArgumentException
141            if the given URI is <NULL/>
142     */
143    XMetadatable getElementByURI([in] XURI URI)
144        raises( com::sun::star::lang::IllegalArgumentException );
145
146    //-------------------------------------------------------------------------
147    /** get the names of all metadata files with a given type.
148
149        @param Type
150            the <code>rdf:type</code> property of the requested named graphs
151
152        @returns
153            the names of all metadata graphs that have a <code>rdf:type</code>
154            property with the given Type as object
155
156        @throws com::sun::star::lang::IllegalArgumentException
157            if the given Type is <NULL/>
158     */
159    sequence<XURI> getMetadataGraphsWithType([in] XURI Type)
160        raises( com::sun::star::lang::IllegalArgumentException );
161
162    //-------------------------------------------------------------------------
163    /** add a metadata file to the manifest.
164
165        <p>
166        This convenience method does the following:
167        <ul>
168        <li>create a new graph with the given name in the repository</li>
169        <li>insert statements declaring the new graph to be a
170            metadata file into the manifest graph</li>
171        <li>insert statements declaring <code>rdf:type</code> properties
172            for the new graph into the manifest graph</li>
173        </ul>
174        </p>
175
176        @param FileName
177            the name of the stream in the ODF storage where the graph will
178            be stored
179
180        @param Types
181            a list of types that will be inserted as <code>rdf:type</code>
182            properties for the graph
183
184        @returns
185            the name of the new graph
186
187        @throws com::sun::star::lang::IllegalArgumentException
188            if the FileName is invalid
189
190        @throws com::sun::star::container::ElementExistException
191            if a stream with the given FileName already exists
192     */
193    XURI addMetadataFile([in] string FileName,
194            [in] sequence<XURI> Types )
195        raises( com::sun::star::lang::IllegalArgumentException,
196                com::sun::star::container::ElementExistException );
197
198    //-------------------------------------------------------------------------
199    /** import a metadata file into the document repository, and add it to the
200        manifest.
201
202        <p>
203        This convenience method does the following:
204        <li>import the given file into a graph with the given name
205            in the repository</li>
206        <li>insert statements declaring the new graph to be a
207            metadata file into the manifest graph</li>
208        <li>insert statements declaring <code>rdf:type</code> properties
209            for the new graph into the manifest graph</li>
210        </p>
211
212        @param FileName
213            the name of the stream in the ODF storage where the graph will
214            be stored
215
216        @param BaseURI
217            a base URI to resolve relative URI references
218
219        @param Types
220            a list of types that will be inserted as <code>rdf:type</code>
221            properties for the graph
222
223        @returns
224            the name of the new graph
225
226        @throws com::sun::star::lang::IllegalArgumentException
227            if the given stream is <NULL/>,
228            or BaseURI is <NULL/> and the format requires use of a base URI,
229            or the FileName is invalid
230
231        @throws com::sun::star::datatransfer::UnsupportedFlavorException
232            if the format requested is unknown or not supported
233
234        @throws com::sun::star::container::ElementExistException
235            if a stream with the given FileName already exists
236
237        @throws ParseException
238            if the input does not conform to the specified file format.
239
240        @throws com::sun::star::io::IOException
241            if an I/O error occurs.
242
243        @see FileFormat
244     */
245    XURI importMetadataFile( [in] /*FileFormat*/ short Format,
246            [in] com::sun::star::io::XInputStream InStream,
247            [in] string FileName, [in] XURI BaseURI,
248            [in] sequence<XURI> Types )
249        raises( com::sun::star::lang::IllegalArgumentException,
250                com::sun::star::datatransfer::UnsupportedFlavorException,
251                com::sun::star::container::ElementExistException,
252                ParseException,
253                com::sun::star::io::IOException );
254
255    //-------------------------------------------------------------------------
256    /** remove a metadata file from the manifest and the repository.
257
258        <p>
259        This convenience method does the following:
260        <li>delete the graph with the given GraphName in the repository</li>
261        <li>remove the statements declaring the graph to be a
262            metadata file from the manifest graph</li>
263        </p>
264
265        @param GraphName
266            the name of the graph that is to be removed
267
268        @throws com::sun::star::lang::IllegalArgumentException
269            if the given GraphName is <NULL/>
270
271        @throws com::sun::star::container::NoSuchElementException
272            if a graph with the given GraphName does not exist
273     */
274    void removeMetadataFile([in] XURI GraphName)
275        raises( com::sun::star::lang::IllegalArgumentException,
276                com::sun::star::container::NoSuchElementException );
277
278    //-------------------------------------------------------------------------
279    /** add a content or styles file to the manifest.
280
281        <p>
282        This convenience method adds the required statements declaring a
283        content or styles file to the manifest graph.
284        <ul>
285        <li>If the FileName ends in "content.xml",
286            an <code>odf:ContentFile</code> is added.</li>
287        <li>If the FileName ends in "styles.xml" ,
288            an <code>odf:StylesFile</code>  is added.</li>
289        <li>Other FileNames are invalid.</li>
290        </ul>
291        </p>
292
293        @param FileName
294            the name of the stream in the ODF storage
295
296        @throws com::sun::star::lang::IllegalArgumentException
297            if the FileName is invalid
298
299        @throws com::sun::star::container::ElementExistException
300            if a stream with the given FileName already exists
301     */
302    void addContentOrStylesFile([in] string FileName)
303        raises( com::sun::star::lang::IllegalArgumentException,
304                com::sun::star::container::ElementExistException );
305
306    //-------------------------------------------------------------------------
307    /** remove a content or styles file from the manifest.
308
309        <p>
310        This convenience method removes the statements declaring a
311        content or styles file from the manifest graph.
312        </p>
313
314        @param FileName
315            the name of the stream in the ODF storage
316
317        @throws com::sun::star::lang::IllegalArgumentException
318            if the FileName is invalid
319
320        @throws com::sun::star::container::NoSuchElementException
321            if a graph with the given GraphName does not exist
322     */
323    void removeContentOrStylesFile([in] string FileName)
324        raises( com::sun::star::lang::IllegalArgumentException,
325                com::sun::star::container::NoSuchElementException );
326
327    //-------------------------------------------------------------------------
328    /** initialize document metadata from a storage.
329
330        <p>
331        This method re-initializes the document metadata,
332        loads the stream named "manifest.rdf" from the storage, and then
333        loads all metadata streams mentioned in the manifest.
334        </p>
335
336        <p>
337        Note that it is not an error if the storage does not contain
338        a manifest.
339        In this case, the document metadata will be default initialized.
340        </p>
341
342        <p>
343        If an InteractionHandler argument is given, it will be used for
344        error reporting. Otherwise, errors will be reported as exceptions.
345        </p>
346
347        @param Storage
348            a storage, representing e.g. an ODF package file, or sub-document
349
350        @param BaseURI
351            a base URI to resolve relative URI references
352            <p>N.B.: when loading from an ODF package, the base URI is not the
353               URI of the package, but the URI of the directory in the package
354               that contains the metadata.rdf</p>
355
356        @param InteractionHandler
357            an InteractionHandler, used for error reporting
358
359        @throws com::sun::star::lang::IllegalArgumentException
360            if any argument is <NULL/>
361
362        @throws com::sun::star::lang::WrappedTargetException
363            if an error occurs while loading and no InteractionHandler given
364     */
365    void loadMetadataFromStorage(
366            [in] com::sun::star::embed::XStorage Storage,
367            [in] XURI BaseURI,
368            [in] com::sun::star::task::XInteractionHandler InteractionHandler )
369        raises( com::sun::star::lang::IllegalArgumentException,
370                com::sun::star::lang::WrappedTargetException );
371
372    //-------------------------------------------------------------------------
373    /** store document metadata to a storage.
374
375        <p>
376        This method stores all the graphs in the document metadata repository
377        to the given storage.
378        </p>
379
380        <p>
381        Note that to be stored correctly, a named graph must have a complete
382        entry in the manifest graph.
383        </p>
384
385        @param Storage
386            a storage, representing e.g. an ODF package file, or sub-document
387
388        @throws com::sun::star::lang::IllegalArgumentException
389            if Storage argument is <NULL/>
390
391        @throws com::sun::star::lang::WrappedTargetException
392            if an error occurs while loading
393     */
394    void storeMetadataToStorage(
395            [in] com::sun::star::embed::XStorage Storage )
396        raises( com::sun::star::lang::IllegalArgumentException,
397                com::sun::star::lang::WrappedTargetException );
398
399    //-------------------------------------------------------------------------
400    /** loads document metadata from a medium.
401
402        <p>If the Medium contains an InteractionHandler, it will be used for
403        error reporting.</p>
404
405        @param Medium
406            the <type>com::sun::star::document::MediaDescriptor</type>
407            representing the source
408
409        @throws com::sun::star::lang::IllegalArgumentException
410            if the argument does not contain a URL or Stream property
411
412        @throws com::sun::star::lang::WrappedTargetException
413            if an error occurs while loading
414
415        @see com::sun::star::document::MediaDescriptor
416     */
417    void loadMetadataFromMedium(
418            [in] sequence < com::sun::star::beans::PropertyValue > Medium )
419        raises( com::sun::star::lang::IllegalArgumentException,
420                com::sun::star::lang::WrappedTargetException );
421
422    //-------------------------------------------------------------------------
423    /** stores document metadata to a medium.
424
425        @param Medium
426            the <type>com::sun::star::document::MediaDescriptor</type>
427            representing the target
428
429        @throws com::sun::star::lang::IllegalArgumentException
430            if the argument does not contain a URL or Stream property
431
432        @throws com::sun::star::lang::WrappedTargetException
433            if an error occurs while storing
434
435        @see com::sun::star::document::MediaDescriptor
436     */
437    void storeMetadataToMedium(
438            [in] sequence < com::sun::star::beans::PropertyValue > Medium )
439        raises( com::sun::star::lang::IllegalArgumentException,
440                com::sun::star::lang::WrappedTargetException );
441
442};
443
444//=============================================================================
445
446}; }; }; };
447
448#endif
449