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