offapi/com/sun/star/sdb/tools/XTableName.idl

   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: XTableName.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  ************************************************************************/
  30
  31 #ifndef __com_sun_star_sdb_tools_XTableName_idl__
  32 #define __com_sun_star_sdb_tools_XTableName_idl__
  33
  34 #ifndef __com_sun_star_lang_IllegalArgumentException_idl__
  35 #include <com/sun/star/lang/IllegalArgumentException.idl>
  36 #endif
  37
  38 #ifndef __com_sun_star_container_NoSuchElementException_idl__
  39 #include <com/sun/star/container/NoSuchElementException.idl>
  40 #endif
  41
  42 #ifndef __com_sun_star_beans_XPropertySet_idl__
  43 #include <com/sun/star/beans/XPropertySet.idl>
  44 #endif
  45
  46 //=============================================================================
  47 module com {  module sun {  module star {  module sdb { module tools {
  48 //=============================================================================
  49
  50 //-----------------------------------------------------------------------------
  51 /** allows to manipulate table names.
  52
  53     <p>When, in a database application, dealing with table names, there's many degrees
  54     of freedom to deal with. For instance, suppose you want to have the full name of a
  55     table object, as it should be used in a <code>SELECT</code> statement's <code>FROM</code>
  56     part. This requires you to evaluate whether or not the table has a catalog and/or schema
  57     name, to combine the catalog, the schema, and the basic table name into one name, respecting
  58     the database's quoting character, and the order in which all those parts should be combined.
  59     Additionally, you have to respect the client-side settings which tell OpenOffice.org
  60     to use or not use catalogs and schemas in <code>SELECT</code> at all.</p>
  61
  62     <p>The <type>XTableName</type> interface eases this and other, similar tasks around table
  63     names.</p>
  64
  65     <p>The component itself does not have life-time control mechanimns, i.e. you
  66     cannot explicitly dispose it (<member scope="com::sun::star::lang">XComponent::dispose</member>),
  67     and you cannot be notified when it dies.<br/>
  68     However, if your try to access any of its methods or attributes, after the
  69     connection which was used to create it was closed, a <type scope="com::sun::star::lang">DisposedException</type>
  70     will be thrown.</p>
  71
  72     @see XConnectionTools
  73     @see com::sun::star::sdbc::XDatabaseMetaData
  74     @see com::sun::star::sdb::DataSource::Settings
  75
  76     @since OOo 2.0.4
  77 */
  78 interface XTableName
  79 {
  80     /** denotes the name of the catalog which the table is a part of
  81     */
  82     [attribute] string  CatalogName;
  83
  84     /** denotes the name of the schema which the table is a part of
  85     */
  86     [attribute] string  SchemaName;
  87
  88     /** denotes the mere, unqualified table name, excluding any catalog and
  89         schema.
  90     */
  91     [attribute] string  TableName;
  92
  93     /** returns the composed table name, including the catalog and schema name,
  94         respecting the databases's quoting requirements, plus
  95
  96         @param Type
  97             the type of name composition to be used.
  98
  99         @param Quote
 100             specifies whether the single parts of the table name should be quoted
 101
 102         @see CompositionType
 103
 104         @throws com::sun::star::IllegalArgumentException
 105             if the given <arg>Type</arg> does not denote a valid <type>CompositionType</type>
 106     */
 107     string  getComposedName( [in] long Type, [in] boolean Quote )
 108         raises ( com::sun::star::lang::IllegalArgumentException );
 109
 110
 111     /** sets a new composed table name
 112         @param ComposedName
 113             specifies the composed table name
 114         @param Type
 115             specifies the composition type which was used to create the composed table name
 116     */
 117     void    setComposedName( [in] string ComposedName, [in] long Type );
 118
 119     /** represents the table name in a form to be used in a <code>SELECT</code> statement.
 120
 121         <p>On a per-data-source basis, OpenOffice.org allows to override database meta
 122         data information in that you can specify to not use catalog and or schema names
 123         in <code>SELECT</code> statements. Using this attribute, you can generate a table
 124         name which respects those settings.</p>
 125
 126         @see com::sun::star::sdb::DataSource::Settings
 127     */
 128     [attribute, readonly]   string  NameForSelect;
 129
 130     /** is the <type scope="com::sun::star::sdb">Table</type> object specified
 131         by the current name.
 132
 133         <p>Retrieving this attribute is equivalent to obtaining the tables
 134         container from the connection (via <type scope="com::sun::star::sdbcx">XTablesSupplier</type>),
 135         and calling its <member scope="com::sun::star::container">XNameAccess::getByName</member>
 136         method with the ComposedName.</p>
 137
 138         @throws com::sun::star::container::NoSuchElementException
 139             if, upon getting the attribute value, the current composed table name
 140             represented by this instance does not denote an existing table in the database.
 141         @throws com::sun::star::lang::IllegalArgumentException
 142             if you try to set an object which does not denote a table from the underlying
 143             database.
 144     */
 145     [attribute] ::com::sun::star::beans::XPropertySet    Table
 146     {
 147         get raises ( com::sun::star::container::NoSuchElementException );
 148         set raises ( com::sun::star::lang::IllegalArgumentException );
 149     };
 150 };
 151
 152 //=============================================================================
 153 }; }; }; }; };
 154 //=============================================================================
 155
 156 #endif
 157