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