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