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

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