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
49module 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*/
65published 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
154