xref: /aoo41x/main/offapi/com/sun/star/sdb/application/CopyTableWizard.idl (revision c4dc0a1a)

/**************************************************************
 *
 * 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
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 *************************************************************/



#ifndef __com_sun_star_sdb_application_CopyTableWizard_idl__
#define __com_sun_star_sdb_application_CopyTableWizard_idl__

#ifndef __com_sun_star_sdb_application_XCopyTableWizard_idl__
#include <com/sun/star/sdb/application/XCopyTableWizard.idl>
#endif
#ifndef __com_sun_star_beans_XPropertySet_idl__
#include <com/sun/star/beans/XPropertySet.idl>
#endif
#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
#include <com/sun/star/lang/IllegalArgumentException.idl>
#endif
#ifndef __com_sun_star_lang_WrappedTargetException_idl__
#include <com/sun/star/lang/WrappedTargetException.idl>
#endif
#ifndef __com_sun_star_task_XInteractionHandler_idl__
#include <com/sun/star/task/XInteractionHandler.idl>
#endif
#ifndef __com_sun_star_sdbc_SQLException_idl__
#include <com/sun/star/sdbc/SQLException.idl>
#endif

//=============================================================================

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
        <member>createWithInteractionHandler</member> 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 <member>createWithInteractionHandler</member>. 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 OpenOffice 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 <type scope="com::sun::star::sdb">DataAccessDescriptor</type> 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 <member scope="com::sun::star::sdb">CommandType::TABLE</member> and
                <member scope="com::sun::star::sdb">CommandType::QUERY</member> are supported.</li>

                <li>If you specify a <code>ConnectionResource</code>, or an
                <code>ActiveConnection</code> which implements an <type scope="com::sun::star::sdbc">Connection</type> only
                (as opposed to a <type scope="com::sun::star::sdb">Connection</type>), 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 <type scope="com::sun::star::sdb">DataAccessDescriptor</type> 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 <type scope="com::sun::star::sdb">Connection</type> service. In particular,
            it is not sufficient to pass an SDBC-level connection.</p>

            <p>Note that creating a view (see <member>CopyTableOperation::CreateAsView</member>) 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 <type scope="com::sun::star::sdbc">SQLException</type> 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 <member>create</member> 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 <type scope="com::sun::star::sdb">InteractionHandler</type>, since
            the general-purpose <type scope="com::sun::star::task">InteractionHandler</type> 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