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