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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef __com_sun_star_resource_XStringResourcePersistence_idl__
  20 #define __com_sun_star_resource_XStringResourcePersistence_idl__
  21
  22 #include <com/sun/star/resource/XStringResourceManager.idl>
  23 #include <com/sun/star/embed/XStorage.idl>
  24 #include <com/sun/star/task/XInteractionHandler.idl>
  25
  26
  27
  28 module com { module sun { module star { module resource {
  29
  30 /**
  31     Interface derived from XStringResourceManager containing
  32     basic persistence functionality limited to operations that
  33     are independent from a associated location or storage.
  34
  35     @see XStringResourceManager.
  36 */
  37 interface XStringResourcePersistence: com::sun::star::resource::XStringResourceManager
  38 {
  39     /**
  40         Stores all string table data respectively all data modified since
  41         the last call to store() to the location or storage
  42         associated with the StringResourceManager. Each locale is stored
  43         in a single file following the format of Java properties files.
  44
  45         This interface is supported by the services
  46         StringResourceWithLocation and
  47         StringResourceWithStorage
  48
  49         The StringResourceWithLocation is initialized with an URL
  50         specifying a location used to load data from and store data to,
  51         see StringResourceWithLocation.
  52
  53         The StringResourceWithStorage is initialized with an instance
  54         of com::sun::star::embed::XStorage
  55         used to load data from and store data to,
  56         see StringResourceWithStorage.
  57
  58         If the string table isn't modified (see isModified())
  59         this method does nothing.
  60
  61         This method can throw all exceptions thrown by the methods of
  62         com::sun::star::embed::XStorage respectively
  63         a com::sun::star::ucb::CommandAbortedException in
  64         case of a StringResourceWithLocation for all exceptions that are
  65         not handled by a previously specified
  66         com::sun::star::task::XInteractionHandler.
  67         The handler to be used for the store operation can be specified
  68         during initialization of StringResourceWithLocation.
  69
  70         @throws com::sun::star::lang::NoSupportException
  71             if no URL or no valid storage are provided.
  72     */
  73     void store()
  74         raises( com::sun::star::lang::NoSupportException,
  75                 com::sun::star::uno::Exception );
  76
  77
  78      /**
  79         provides the current modify state of the StringResourceManager instance.
  80
  81         @return
  82             `TRUE` if the string table has changed since the last call to
  83             store() or, if supported
  84             <code>XStringResourceWithStorage::storeAsStorage</code>.
  85             `FALSE` if the table hasn't changed.
  86     */
  87     boolean isModified();
  88
  89
  90     /**
  91         Sets the comment stored first in each locale data file.
  92
  93         This interface method can be used to overwrite the comment used
  94         during initialization of the services
  95         StringResourceWithLocation or
  96         StringResourceWithStorage
  97
  98         @param Comment
  99             Comment stored first in each properties file followed by a line
 100             feed character. The line feed character is added automatically
 101             and hasn't to be part of the comment string. The caller is
 102             responsible that the passed string is a valid comment in a Java
 103             properties file, e.g. "# My strings". The string may be empty.
 104     */
 105     void setComment( [in] string Comment );
 106
 107
 108     /**
 109         Stores all string table data to the provided storage.
 110
 111         Calling this method does not affect the association with a location
 112         (in case of a StringResourceWithLocation instance)
 113         respectively with a storage (in case of a
 114         StringResourceWithStorage instance).
 115         The modified state isn't affected either.
 116
 117         This method can be used to make a copy of the current string
 118         table data to a storage. This method can throw all exceptions
 119         thrown by the methods of com::sun::star::embed::XStorage
 120
 121         @param Storage
 122             all string table data will be stored to this storage.
 123
 124         @param BaseName
 125             Base string for the file names used to store the locale data.
 126             The locale data is stored in Java properties files also following
 127             the corresponding naming scheme. The files will be named like this:
 128             "[BaseName]_[Language]_[Country].properties",
 129             e.g. "MyBaseName_en_US.properties"
 130             If an empty string is passed for BaseName, "strings" will be used
 131             as BaseName.
 132
 133         @param Comment
 134             Comment stored first in each properties file,
 135             for a detailed description see setComment().
 136
 137         This method can throw all exceptions thrown by the methods of
 138         com::sun::star::embed::XStorage
 139     */
 140     void storeToStorage( [in] ::com::sun::star::embed::XStorage Storage,
 141         [in] string BaseName, [in] string Comment )
 142             raises ( com::sun::star::uno::Exception );
 143
 144
 145     /**
 146         Stores all string table data to the location specified by the
 147         passed URL string.
 148
 149         Calling this method does not affect the association with a location
 150         (in case of a StringResourceWithLocation instance)
 151         respectively with a storage (in case of a
 152         StringResourceWithStorage instance).
 153         The modified state isn't affected either.
 154
 155         This method can be used to make a copy of the current string
 156         table data to a location.
 157
 158         @param URL
 159             the location the string table data should be stored to.
 160
 161         @param BaseName
 162             Base string for the file names used to store the locale data.
 163             The locale data is stored in Java properties files also following
 164             the corresponding naming scheme. The files will be named like this:
 165             "[BaseName]_[Language]_[Country].properties",
 166             e.g. "MyBaseName_en_US.properties"
 167             If an empty string is passed for BaseName, "strings" will be used
 168             as BaseName.
 169
 170         @param Comment
 171             Comment stored first in each properties file,
 172             for a detailed description see setComment().
 173
 174         @param Handler
 175             a com::sun::star::task::XInteractionHandler.
 176             It will be passed to ucb handle exceptions. Exceptions not processed
 177             by this handler will be passed as com::sun::star::uno::Exception. If
 178             this parameter is null this applies to all exceptions thrown by ucb.
 179
 180         @see com::sun::star::task::InteractionHandler
 181     */
 182     void storeToURL( [in] string URL, [in] string BaseName, [in] string Comment,
 183         [in] com::sun::star::task::XInteractionHandler Handler )
 184             raises( com::sun::star::uno::Exception );
 185
 186
 187     /**
 188         Returns a sequence of byte representing the complete string resource
 189         in a binary format.
 190
 191         This method is intended to support datatransfer functionality, e.g. provided
 192         by com::sun::star::datatransfer::XTransferable and
 193         related interfaces.
 194
 195         See importBinary()).
 196
 197         @return  a sequence of byte representing the string resource.
 198     */
 199     sequence<byte> exportBinary();
 200
 201
 202     /**
 203         Initializes the string resource with binary data. This method
 204         expects the data format returned by exportBinary().
 205
 206         All locales and strings previously added to the string resource
 207         will be deleted. So after calling this method the string resource
 208         only contains the locales and strings specified in the binary data.
 209
 210         This method is intended to support datatransfer functionality, e.g. provided
 211         by com::sun::star::datatransfer::XTransferable and
 212         related interfaces.
 213
 214         See importBinary()).
 215
 216         @throws com::sun::star::lang::IllegalArgumentException
 217         if Data is empty or does not meet the binary format returned by
 218         the current or earlier version of exportBinary()).
 219     */
 220     void importBinary( [in] sequence<byte> Data )
 221         raises ( com::sun::star::lang::IllegalArgumentException );
 222
 223 };
 224
 225
 226 }; }; }; };
 227
 228 #endif
 229
 230 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */