offapi/com/sun/star/ucb/XCommandProcessor.idl

   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_ucb_XCommandProcessor_idl__
  29 #define __com_sun_star_ucb_XCommandProcessor_idl__
  30
  31 #ifndef __com_sun_star_uno_XInterface_idl__
  32 #include <com/sun/star/uno/XInterface.idl>
  33 #endif
  34
  35 #ifndef __com_sun_star_ucb_XCommandEnvironment_idl__
  36 #include <com/sun/star/ucb/XCommandEnvironment.idl>
  37 #endif
  38
  39 #ifndef __com_sun_star_ucb_Command_idl__
  40 #include <com/sun/star/ucb/Command.idl>
  41 #endif
  42
  43 #ifndef __com_sun_star_ucb_CommandAbortedException_idl__
  44 #include <com/sun/star/ucb/CommandAbortedException.idl>
  45 #endif
  46
  47 //=============================================================================
  48
  49 module com { module sun { module star { module ucb {
  50
  51 //=============================================================================
  52 /** defines a processor for synchronous commands, which are executed in a
  53     specific execution environment.
  54
  55     @version  1.0
  56     @author   Kai Sommerfeld
  57
  58     @see com::sun::star::ucb::XCommandProcessor2
  59     for the improved version of this interface.
  60
  61     @see      Command
  62     @see      XCommandEnvironment
  63     @see      XContent
  64 */
  65 published interface XCommandProcessor : com::sun::star::uno::XInterface
  66 {
  67     //-------------------------------------------------------------------------
  68     /** creates a unique identifier for a command.
  69
  70         <p>This identifier can be used to abort the execution of the command
  71         accociated with that identifier. Note that it is generally not
  72         necessary to obtain a new id for each command, because commands are
  73         executed synchronously. So the id for a command is valid again after a
  74         command previously associated with this id has finished. In fact you
  75         only should get one identifier per thread and assign it to every
  76         command executed by that thread.</p>
  77
  78         <p>Also, after a call to <member>XCommandProcessor::abort</member>, an
  79         identifier should not be used any longer (and instead be released by a
  80         call to <member>XCommandProcessor2::releaseCommandIdentifier</member>),
  81         because it may well abort <em>all</em> further calls to
  82         <member>XCommandProcessor::execute</member>.</p>
  83
  84         <p>To avoid ever-increasing resource consumption, the identifier
  85         should be released via
  86         <member>XCommandProcessor2::releaseCommandIdentifier</member>
  87         when it is no longer used.</p>
  88
  89         @returns
  90         a command identifier.
  91     */
  92     long createCommandIdentifier();
  93
  94     //-------------------------------------------------------------------------
  95     /** executes a command.
  96
  97         <p>Common command definitions can be found in the soecification of the
  98         service <type>Content</type>.
  99
 100         @param aCommand
 101         is the command to execute.
 102
 103         @param CommandId
 104         is a unique id for the command. This identifier was obtained by calling
 105         <member>XCommandProcessor::createCommandIdentifier</member>. A value of
 106         zero can be used, if the command never shall be aborted. Different
 107         threads MUST NOT share one command identifier (except <code>0</code>).
 108         This can easily achieved, if every thread that wants to use an
 109         <type>XCommandProcessor</type>, obtains exactly one identifier
 110         using <member>XCommandProcessor::createCommandIdentifier</member>.
 111         This identifier can be used for every call to
 112         <member>XCommandProcessor::execute</member> done by that thread.
 113
 114         @param Environment
 115         is the execution environment.
 116
 117         @returns
 118         the result according to the specification of the command.
 119
 120         @throws CommandAbortedException
 121         to indicate that the command was aborted.
 122
 123         @throws DuplicateCommandIdentifierException
 124         to indicate that two threads tried to use the same command identifier
 125
 126         @throws Exception
 127         if an error occured during the execution of the command.
 128     */
 129     any execute( [in] Command aCommand,
 130                  [in] long CommandId,
 131                  [in] XCommandEnvironment Environment )
 132         raises ( com::sun::star::uno::Exception, CommandAbortedException );
 133
 134     //-------------------------------------------------------------------------
 135     /** ends the command associated with the given id.
 136
 137         <p>Not every command can be aborted. It's up to the implementation
 138         to decide whether this method will actually end the processing of
 139         the command or simply do nothing.
 140
 141         @param CommandId
 142         is a unique id for the command to abort. This must be the identifier
 143         passed to <member>XCommandProcessor::execute</member> for the command
 144         to abort.
 145     */
 146     [oneway] void abort( [in] long CommandId );
 147 };
 148
 149 //=============================================================================
 150
 151 }; }; }; };
 152
 153 #endif