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