1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23
24#ifndef __com_sun_star_sdb_tools_XTableName_idl__
25#define __com_sun_star_sdb_tools_XTableName_idl__
26
27#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
28#include <com/sun/star/lang/IllegalArgumentException.idl>
29#endif
30
31#ifndef __com_sun_star_container_NoSuchElementException_idl__
32#include <com/sun/star/container/NoSuchElementException.idl>
33#endif
34
35#ifndef __com_sun_star_beans_XPropertySet_idl__
36#include <com/sun/star/beans/XPropertySet.idl>
37#endif
38
39//=============================================================================
40module com {  module sun {  module star {  module sdb { module tools {
41//=============================================================================
42
43//-----------------------------------------------------------------------------
44/** allows to manipulate table names.
45
46    <p>When, in a database application, dealing with table names, there's many degrees
47    of freedom to deal with. For instance, suppose you want to have the full name of a
48    table object, as it should be used in a <code>SELECT</code> statement's <code>FROM</code>
49    part. This requires you to evaluate whether or not the table has a catalog and/or schema
50    name, to combine the catalog, the schema, and the basic table name into one name, respecting
51    the database's quoting character, and the order in which all those parts should be combined.
52    Additionally, you have to respect the client-side settings which tell OpenOffice.org
53    to use or not use catalogs and schemas in <code>SELECT</code> at all.</p>
54
55    <p>The <type>XTableName</type> interface eases this and other, similar tasks around table
56    names.</p>
57
58    <p>The component itself does not have life-time control mechanimns, i.e. you
59    cannot explicitly dispose it (<member scope="com::sun::star::lang">XComponent::dispose</member>),
60    and you cannot be notified when it dies.<br/>
61    However, if your try to access any of its methods or attributes, after the
62    connection which was used to create it was closed, a <type scope="com::sun::star::lang">DisposedException</type>
63    will be thrown.</p>
64
65    @see XConnectionTools
66    @see com::sun::star::sdbc::XDatabaseMetaData
67    @see com::sun::star::sdb::DataSource::Settings
68
69    @since OpenOffice 2.0.4
70*/
71published interface XTableName
72{
73    /** denotes the name of the catalog which the table is a part of
74    */
75    [attribute] string  CatalogName;
76
77    /** denotes the name of the schema which the table is a part of
78    */
79    [attribute] string  SchemaName;
80
81    /** denotes the mere, unqualified table name, excluding any catalog and
82        schema.
83    */
84    [attribute] string  TableName;
85
86    /** returns the composed table name, including the catalog and schema name,
87        respecting the databases's quoting requirements, plus
88
89        @param Type
90            the type of name composition to be used.
91
92        @param Quote
93            specifies whether the single parts of the table name should be quoted
94
95        @see CompositionType
96
97        @throws com::sun::star::IllegalArgumentException
98            if the given <arg>Type</arg> does not denote a valid <type>CompositionType</type>
99    */
100    string  getComposedName( [in] long Type, [in] boolean Quote )
101        raises ( com::sun::star::lang::IllegalArgumentException );
102
103
104    /** sets a new composed table name
105        @param ComposedName
106            specifies the composed table name
107        @param Type
108            specifies the composition type which was used to create the composed table name
109    */
110    void    setComposedName( [in] string ComposedName, [in] long Type );
111
112    /** represents the table name in a form to be used in a <code>SELECT</code> statement.
113
114        <p>On a per-data-source basis, OpenOffice.org allows to override database meta
115        data information in that you can specify to not use catalog and or schema names
116        in <code>SELECT</code> statements. Using this attribute, you can generate a table
117        name which respects those settings.</p>
118
119        @see com::sun::star::sdb::DataSource::Settings
120    */
121    [attribute, readonly]   string  NameForSelect;
122
123    /** is the <type scope="com::sun::star::sdb">Table</type> object specified
124        by the current name.
125
126        <p>Retrieving this attribute is equivalent to obtaining the tables
127        container from the connection (via <type scope="com::sun::star::sdbcx">XTablesSupplier</type>),
128        and calling its <member scope="com::sun::star::container">XNameAccess::getByName</member>
129        method with the ComposedName.</p>
130
131        @throws com::sun::star::container::NoSuchElementException
132            if, upon getting the attribute value, the current composed table name
133            represented by this instance does not denote an existing table in the database.
134        @throws com::sun::star::lang::IllegalArgumentException
135            if you try to set an object which does not denote a table from the underlying
136            database.
137    */
138    [attribute] ::com::sun::star::beans::XPropertySet    Table
139    {
140        get raises ( com::sun::star::container::NoSuchElementException );
141        set raises ( com::sun::star::lang::IllegalArgumentException );
142    };
143};
144
145//=============================================================================
146}; }; }; }; };
147//=============================================================================
148
149#endif
150
151