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