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