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_sdb_application_CopyTableWizard_idl__
29#define __com_sun_star_sdb_application_CopyTableWizard_idl__
30
31#ifndef __com_sun_star_sdb_application_XCopyTableWizard_idl__
32#include <com/sun/star/sdb/application/XCopyTableWizard.idl>
33#endif
34#ifndef __com_sun_star_beans_XPropertySet_idl__
35#include <com/sun/star/beans/XPropertySet.idl>
36#endif
37#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
38#include <com/sun/star/lang/IllegalArgumentException.idl>
39#endif
40#ifndef __com_sun_star_lang_WrappedTargetException_idl__
41#include <com/sun/star/lang/WrappedTargetException.idl>
42#endif
43#ifndef __com_sun_star_task_XInteractionHandler_idl__
44#include <com/sun/star/task/XInteractionHandler.idl>
45#endif
46#ifndef __com_sun_star_sdbc_SQLException_idl__
47#include <com/sun/star/sdbc/SQLException.idl>
48#endif
49
50//=============================================================================
51
52module com { module sun { module star { module sdb { module application {
53
54//=============================================================================
55
56/** describes a wizard which can be used to copy table like data from one
57    database to another.
58
59    <dt><b><a name="interaction"></a>Interactions</b></dt>
60    <dd>
61        <p>There are various cases where the wizard needs to interact with the user (except of
62        course the obvious case to display and operate the wizard dialog itself). For those cases,
63        an interaction handler is needed, which is used for
64        <ul>
65            <li>fulfilling parameter requests. This might become necessary if the copy source
66            describes a parametrized query.</li>
67            <li>user interaction in case copying a row fails. If no copy table listener is
68            registered at the wizard, or none of the registered listener handles an error during
69            copying a row, or a registered listeners explicitly tells the wizard to ask the user
70            how to handle the error, then the interaction handler is used together with the
71            error (an <code>SQLException</code>, usually) that happened.</li>
72            <li>displaying other errors which happen during copying, in particular errors in
73            creating the target table or view.</li>
74        </ul></p>
75
76        <p>When you do not specify an interaction handler by using the
77        <member>createWithInteractionHandler</member> constructor, the wizard will use the interaction
78        handler associated with the copy target, i.e. the interaction handler specified when loading
79        the document which the copy target refers to. If the copy target cannot be associated with
80        a database document (e.g. because it is a mere <code>ConnectionResource</code>, or a connection
81        not obtained from a data source), or if the copy target's database document cannot provide
82        an interaction handler, a newly-created instance of an interaction handler is used.</p>
83
84        <p>There's one exception to the above, however: Upon creating the copy table wizard,
85        the copy source and the copy target descriptors are used to create a Connection. For any
86        interaction during this phase - including, for instance, necessary authentication -, the
87        interaction handler of the respective data source is used, no matter what you specified
88        in <member>createWithInteractionHandler</member>. Only if there is no such interaction
89        handler, the processing described above, to find another handler, is applied.</p>
90    </dd>
91
92    @see ::com::sun::star::sdb::ParametersRequest
93    @see XCopyTableWizard::addCopyTableListener
94    @see CopyTableContinuation
95    @see ::com::sun::star::document::MediaDescriptor::InteractionHandler
96    @see ::com::sun::star::sdb::DatabaseDocument
97    @see ::com::sun::star::sdb::DataSource
98    @see ::com::sun::star::sdb::DataAccessDescriptor::ConnectionResource
99    @see ::com::sun::star::sdb::InteractionHandler
100
101    @since OOo 2.4
102 */
103service CopyTableWizard : XCopyTableWizard
104{
105    /** creates an executable wizard dialog, which is to guide the user through copying
106        a table from one database to another.
107
108        <p>At creation time, an attempt will be made to obtain the connections described
109        by <arg>Source</arg> resp. <arg>Dest</arg>. Failing to do so will result in an
110        exception.</p>
111
112        <p>If the connection has been newly created by the wizard (e.g. because the
113        data access descriptor specified a <code>DataSource</code> instead of an <code>ActiveConnection</code>),
114        then this connection will be disposed upon disposal of the wizard.</p>
115
116        @param Source
117            the <type scope="com::sun::star::sdb">DataAccessDescriptor</type> describing the
118            data to copy.
119
120            <p>The following members of the <code>DataAccessDescriptor</code> are supported, and evaluated
121            in the given order:
122            <ol><li><code>ActiveConnection</code></li>
123                <li><code>DataSourceName</code></li>
124                <li><code>DatabaseLocation</code></li>
125                <li><code>ConnectionResource</code></li>
126                <li><code>ConnectionInfo</code></li>
127                <li><code>Command</code></li>
128                <li><code>CommandType</code></li>
129            </ol>
130            The first 5 items are used to obtain the connection, the last two to determine which
131            of the connection's objects is to be copied. Note that <code>Command</code> and <code>CommandType</code>
132            are required.</p>
133
134            <p>Additionally to the obvious restrictions (such as that creating a view is not possible
135            if the copy source and the copy destination denote different databases), the following restrictions
136            apply to the settings, and possible combinations:
137            <ul><li>Only <member scope="com::sun::star::sdb">CommandType::TABLE</member> and
138                <member scope="com::sun::star::sdb">CommandType::QUERY</member> are supported.</li>
139
140                <li>If you specify a <code>ConnectionResource</code>, or an
141                <code>ActiveConnection</code> which implements an <type scope="com::sun::star::sdbc">Connection</type> only
142                (as opposed to a <type scope="com::sun::star::sdb">Connection</type>), then the resulting connection is
143                not able to provide queries, thus a command type <code>QUERY</code> will be rejected.</li>
144
145                <li><code>Filter</code>, <code>Order</code>, <code>HavingClause</code> and <code>GroupBy</code>
146                are unsupported at the moment.</li>
147            </ul>
148            Violating any of the above restrictions will result in an error at creation time.</p>
149
150        @param Destination
151            the <type scope="com::sun::star::sdb">DataAccessDescriptor</type> describing the
152            target for the copy operation.
153
154            <p>Only <code>DataSourceName</code>, <code>DatabaseLocation</code>, <code>ActiveConnection</code>
155            are supported, effectively describing the target connection to copy the data to. They're evaluated
156            in the order mentioned here, so if multiple of the are present, only the first one is evaluated.</p>
157
158            <p>Also, at the moment the connection which is implied by either of the settings above
159            must support the <type scope="com::sun::star::sdb">Connection</type> service. In particular,
160            it is not sufficient to pass an SDBC-level connection.</p>
161
162            <p>Note that creating a view (see <member>CopyTableOperation::CreateAsView</member>) is
163            not supported if the target connection is an SDBC-level connection only.</p>
164
165        @throws ::com::sun::star::lang::IllegalArgumentException
166            if
167            <ul><li>either <code>Source</code> or <code>Destination</code> is <NULL/></li>
168                <li>either <code>Source</code> or <code>Destination</code> are not sufficient
169                    to describe a database connection.</li>
170                <li><code>Source</code> is not sufficient to describe the to-be-copied data</li>
171                <li>either <code>Source</code> or <code>Destination</code> contain unsupported settings.</li>
172            </ul>
173
174        @throws ::com::sun::star::sdbc::SQLException
175            if an error occurs during obtaining the source or destination connection. Those errors
176            are passed unchanged to the creator of the wizard.
177
178        @throws ::com::sun::star::lang::WrappedTargetException
179            if an error other than the ones mentioned above occurs while extracting the necessary
180            information from any of the data access descriptors. For instance, this might
181            be an <type scope="com::sun::star::sdbc">SQLException</type> thrown upon connecting
182            to a data source described by the descriptor's <code>DataSourceName</code> member.
183
184        @see ::com::sun::star::sdb::DataAccessDescriptor
185    */
186    create(
187        [in] ::com::sun::star::beans::XPropertySet Source,
188        [in] ::com::sun::star::beans::XPropertySet Destination
189    )
190        raises  (   ::com::sun::star::lang::IllegalArgumentException
191                ,   ::com::sun::star::sdbc::SQLException
192                ,   ::com::sun::star::lang::WrappedTargetException
193                );
194
195    /** creates an executable wizard dialog, which is to guide the user through copying
196        a table from one database to another.
197
198        <p>The only difference to the <member>create</member> constructor is that
199        <code>createWithInteractionHandler</code> takes an additional argument, which
200        can be used to intercept interactions (such as error messages) during the wizard
201        run.</p>
202
203        @param InteractionHandler
204            specifies an interaction handler to use when user input is required.
205
206            <p>When specifying this parameter, you should use an implementation
207            supporting the <type scope="com::sun::star::sdb">InteractionHandler</type>, since
208            the general-purpose <type scope="com::sun::star::task">InteractionHandler</type> cannot
209            handle all requests described <a href="#interaction">above</a>.</p>
210
211        @see ::com::sun::star::sdb::InteractionHandler
212    */
213    createWithInteractionHandler(
214        [in] ::com::sun::star::beans::XPropertySet Source,
215        [in] ::com::sun::star::beans::XPropertySet Destination,
216        [in] ::com::sun::star::task::XInteractionHandler InteractionHandler
217    )
218        raises  (   ::com::sun::star::lang::IllegalArgumentException
219                ,   ::com::sun::star::sdbc::SQLException
220                ,   ::com::sun::star::lang::WrappedTargetException
221                );
222
223};
224
225//=============================================================================
226
227}; }; }; }; };
228
229//=============================================================================
230
231#endif
232