offapi/com/sun/star/resource/XStringResourcePersistence.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XStringResourcePersistence.idl,v $
  10  * $Revision: 1.3 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  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.
  17  *
  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).
  23  *
  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.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_resource_XStringResourcePersistence_idl__
  31 #define __com_sun_star_resource_XStringResourcePersistence_idl__
  32
  33 #ifndef __com_sun_star_resource_XStringResourceManager_idl__
  34 #include <com/sun/star/resource/XStringResourceManager.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_embed_XStorage_idl__
  38 #include <com/sun/star/embed/XStorage.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_task_XInteractionHandler_idl__
  42 #include <com/sun/star/task/XInteractionHandler.idl>
  43 #endif
  44
  45
  46 //=============================================================================
  47
  48 module com { module sun { module star { module resource {
  49
  50 //=============================================================================
  51 /**
  52     Interface derived from XStringResourceManager containing
  53     basic persistence functionality limited to operations that
  54     are independend from a associated location or storage.
  55
  56     @see <type>XStringResourceManager</type>.
  57 */
  58 interface XStringResourcePersistence: com::sun::star::resource::XStringResourceManager
  59 {
  60     /**
  61         Stores all string table data respectively all data modified since
  62         the last call to <member>store</member> to the location or storage
  63         associated with the StringResourceManager. Each locale is stored
  64         in a single file following the format of Java properties files.
  65
  66         This interface is supported by the services
  67         <type>StringResourceWithLocation</type> and
  68         <type>StringResourceWithStorage</type>
  69
  70         The StringResourceWithLocation is initialised with an URL
  71         specifying a location used to load data from and store data to,
  72         see <type>StringResourceWithLocation</type>.
  73
  74         The StringResourceWithStorage is initialised with an in-
  75         stance of <type scope="com::sun::star::embed">XStorage</type>
  76         used to load data from and store data to,
  77         see <type>StringResourceWithStorage</type>.
  78
  79         If the string table isn't modified (see <member>isModified</member>)
  80         this method does nothing.
  81
  82         This method can throw all exceptions thrown by the methods of
  83         <type scope="com::sun::star::embed">XStorage</type> respectively
  84         a <type scope="com::sun::star::ucb">CommandAbortedException in
  85         case of a StringResourceWithLocation for all exceptions that are
  86         not handled by a previously specified
  87         <type scope="com::sun::star::task">XInteractionHandler</type>.
  88         The handler to be used for the store operation can be specified
  89         during initialisation of <type>StringResourceWithLocation</type>.
  90
  91         @throws <type scope="com::sun::star::lang">NoSupportException</type>
  92             if no URL or no valid storage are provided.
  93     */
  94     void store()
  95         raises( com::sun::star::lang::NoSupportException,
  96                 com::sun::star::uno::Exception );
  97
  98
  99      /**
 100         provides the current modify state of the StringResourceManager instance.
 101
 102         @return
 103             <TRUE/> if the string table has changed since the last call to
 104             <member>store</member> or, if supported
 105             <code>XStringResourceWithStorage::storeAsStorage</code>.
 106             <FALSE/> if the table hasn't changed.
 107     */
 108     boolean isModified();
 109
 110
 111     /**
 112         Sets the comment stored first in each locale data file.
 113
 114         This interface method can be used to overwrite the comment used
 115         during initialisation of the services
 116         <type>StringResourceWithLocation</type> or
 117         <type>StringResourceWithStorage</type>
 118
 119         @param Comment
 120             Comment stored first in each properties file followed by a line
 121             feed character. The line feed character is added automatically
 122             and hasn't to be part of the comment string. The caller is re-
 123             sponsible that the passed string is a valid comment in a Java
 124             properties file, e.g. "# My strings". The string may be empty.
 125     */
 126     void setComment( [in] string Comment );
 127
 128
 129     /**
 130         Stores all string table data to the provided storage.
 131
 132         Calling this method does not affect the association with a location
 133         (in case of a <type>StringResourceWithLocation</type> instance)
 134         repectively with a storage (in case of a
 135         <type>StringResourceWithStorage</type> instance).
 136         The modified state isn't affected either.
 137
 138         This method can be used to make a copy of the current string
 139         table data to a storage. This method can throw all exceptions
 140         thrown by the methods of <type scope="com::sun::star::embed">XStorage</type>
 141
 142         @param Storage
 143             all string table data will be stored to this storage.
 144
 145         @param BaseName
 146             Base string for the file names used to store the locale data.
 147             The locale data is stored in Java properties files also following
 148             the corresponding naming sceme. The files will be named like this:
 149             "[BaseName]_[Language]_[Country].properties",
 150             e.g. "MyBaseName_en_US.properties"
 151             If an empty string is passed for BaseName, "strings" will be used
 152             as BaseName.
 153
 154         @param Comment
 155             Comment stored first in each properties file,
 156             for a detailed description see <member>setComment</member>.
 157
 158         This method can throw all exceptions thrown by the methods of
 159         <type scope="com::sun::star::embed">XStorage</type>
 160     */
 161     void storeToStorage( [in] ::com::sun::star::embed::XStorage Storage,
 162         [in] string BaseName, [in] string Comment )
 163             raises ( com::sun::star::uno::Exception );
 164
 165
 166     /**
 167         Stores all string table data to the location specified by the
 168         passed URL string.
 169
 170         Calling this method does not affect the association with a location
 171         (in case of a <type>StringResourceWithLocation</type> instance)
 172         repectively with a storage (in case of a
 173         <type>StringResourceWithStorage</type> instance).
 174         The modified state isn't affected either.
 175
 176         This method can be used to make a copy of the current string
 177         table data to a location.
 178
 179         @param URL
 180             the location the string table data should be stored to.
 181
 182         @param BaseName
 183             Base string for the file names used to store the locale data.
 184             The locale data is stored in Java properties files also following
 185             the corresponding naming sceme. The files will be named like this:
 186             "[BaseName]_[Language]_[Country].properties",
 187             e.g. "MyBaseName_en_US.properties"
 188             If an empty string is passed for BaseName, "strings" will be used
 189             as BaseName.
 190
 191         @param Comment
 192             Comment stored first in each properties file,
 193             for a detailed description see <member>setComment</member>.
 194
 195         @param Handler
 196             a <type scope="com::sun::star::task">XInteractionHandler</type>.
 197             It will be passed to ucb handle exceptions. Exceptions not processed
 198             by this handler will be passed as com::sun::star::uno::Exception. If
 199             this parameter is null this applies to all exceptions thrown by ucb.
 200
 201         @see com::sun::star::task::InteractionHandler
 202     */
 203     void storeToURL( [in] string URL, [in] string BaseName, [in] string Comment,
 204         [in] com::sun::star::task::XInteractionHandler Handler )
 205             raises( com::sun::star::uno::Exception );
 206
 207
 208     /**
 209         Returns a sequence of byte representing the complete string resource
 210         in a binary format.
 211
 212         This method is intended to support datatransfer functionality, e.g. provided
 213         by <type scope="com::sun::star::datatransfer">XTransferable</type> and
 214         related interfaces.
 215
 216         See <member>importBinary</member>).
 217
 218         @return  a sequence of byte representing the string resource.
 219     */
 220     sequence<byte> exportBinary();
 221
 222
 223     /**
 224         Initializes the string resource with binary data. This method
 225         expects the data format returned by <member>exportBinary</member>.
 226
 227         All locales and strings previously added to the string resource
 228         will be deleted. So after calling this method the string resource
 229         only contains the locales and strings specified in the binary data.
 230
 231         This method is intended to support datatransfer functionality, e.g. provided
 232         by <type scope="com::sun::star::datatransfer">XTransferable</type> and
 233         related interfaces.
 234
 235         See <member>importBinary</member>).
 236
 237         @throws com::sun::star::lang::IllegalArgumentException
 238         if Data is empty or does not meet the binary format returned by
 239         the current or earlier version of <member>exportBinary</member>).
 240     */
 241     void importBinary( [in] sequence<byte> Data )
 242         raises ( com::sun::star::lang::IllegalArgumentException );
 243
 244 };
 245
 246 //=============================================================================
 247
 248 }; }; }; };
 249
 250 #endif