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