udkapi/com/sun/star/test/XTest.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: XTest.idl,v $
  10  * $Revision: 1.10 $
  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 #ifndef __com_sun_star_test_XTest_idl__
  31 #define __com_sun_star_test_XTest_idl__
  32
  33 #ifndef __com_sun_star_uno_XInterface_idl__
  34 #include <com/sun/star/uno/XInterface.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_lang_IllegalArgumentException_idl__
  38 #include <com/sun/star/lang/IllegalArgumentException.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_test_XTestListener_idl__
  42 #include <com/sun/star/test/XTestListener.idl>
  43 #endif
  44
  45
  46 //=============================================================================
  47
  48 module com { module sun { module star { module test {
  49
  50 //=============================================================================
  51 /**
  52     A simple interface to test a service or interface implementation.
  53 */
  54 published interface XTest: com::sun::star::uno::XInterface
  55 {
  56     //-------------------------------------------------------------------------
  57     /**
  58         Test the object TestObject against the test specified with TestName. This test
  59         does not change the semantic state of the object, so it can be called on a existing
  60         component that will used further on. Note: This can be a strong test limitation.
  61         There are some components, that cannot perform their full test scenario.
  62         @param TestName
  63             the name of the test. Must be an interface, service, or implementation name.
  64             Note: The name is only used by the test component to distinguish between test
  65             scenarios.
  66         @param TestObject
  67                 The instance to be tested.
  68         @throws IllegalArgumentException
  69             if the test does not support TestName or TestObject is null.
  70     */
  71     void testInvariant( [in] string TestName,
  72              [in] com::sun::star::uno::XInterface TestObject )
  73             raises( com::sun::star::lang::IllegalArgumentException );
  74
  75     //-------------------------------------------------------------------------
  76     /**
  77         Test the object TestObject against the test specified with TestName.
  78         This test changes the state of the object. The object may be useless
  79         afterwards (e.g., a closed XOutputStream). The method in general may
  80         be called multiple times with a new test object instance. Note: Each test
  81         scenario should be independent of each other, so even if a scenario
  82         didn't pass the test, the other test can still be performed.
  83         The error messages are cumulative.
  84
  85         @param TestName
  86             The name of the test. Must be an interface, service, or
  87             implementation name. Note: The name is only used by the test component
  88             to distinguish between test scenarios.
  89         @param TestObject
  90                 The instance to be tested.
  91         @param hTestHandle
  92                 Internal test handle. Handle for first test is always 0.
  93             Handle of next test is  returned by the method.
  94         @return Handle of the next test. -1 if this was the last test.
  95
  96         @throws IllegalArgumentException
  97             if the test does not support TestName or TestObject is null.
  98     */
  99     long test( [in] string TestName,
 100              [in] com::sun::star::uno::XInterface TestObject,
 101              [in] long hTestHandle )
 102             raises( com::sun::star::lang::IllegalArgumentException );
 103
 104     //-------------------------------------------------------------------------
 105     /**
 106         Test the object TestObject against the test specified with TestName     using
 107         several threads. That does NOT mean that testMultiThread should implement
 108         a test using several threads but that this test method should be designed
 109         to be called by several threads. So for example, it has to take into consideration
 110         that a test object state that is changed by the method  can be
 111         changed again by another thread. So it's not necessarily a mistake if an
 112         expected state can't be confirmed after setting it. Besides that, everything
 113         is the same as described for the test method.
 114
 115         If this way of testing with multiple threads is not appropriate for the
 116         component to be tested this method should not be implemented (it should
 117         only return -1) and a special multithread test adapted to the special
 118         needs of testing this component should be integrated in the test method.
 119
 120         @param TestName
 121             The name of the test. Must be an interface, service or
 122             implementation name. Note: The name is only used by the test component
 123             to distinguish between test scenarios.
 124         @param TestObject
 125             The instance to be tested.
 126         @param hTestHandle
 127             Internal test handle. Handle for first test is always 0.
 128             Handle of next test is  returned by the method.
 129         @return Handle of the next test. -1 if this was the last test.
 130
 131         @throws IllegalArgumentException
 132             if the test does not support TestName or TestObject is null.
 133     */
 134     long testMultiThread( [in] string TestName,
 135              [in] com::sun::star::uno::XInterface TestObject,
 136              [in] long hTestHandle )
 137             raises( com::sun::star::lang::IllegalArgumentException );
 138
 139     //-------------------------------------------------------------------------
 140     /** registers an event listener, which will be called for reporting
 141         errors/exceptions and warnings and for protocol purpuses.
 142     */
 143     void addTestListener( [in] XTestListener xListener );
 144
 145     //-------------------------------------------------------------------------
 146     /** unregisters an event listener which was registered with
 147         <member>XTest::addTestListener()</member>.
 148
 149     */
 150     void removeTestListener( [in] XTestListener xListener );
 151
 152 };
 153
 154 //=============================================================================
 155
 156 }; }; }; };
 157
 158 #endif