forms/source/xforms/binding.hxx

   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: binding.hxx,v $
  10  * $Revision: 1.6 $
  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 _BINDING_HXX
  32 #define _BINDING_HXX
  33
  34 #include <com/sun/star/uno/Reference.hxx>
  35
  36 // forward declaractions
  37 namespace xforms
  38 {
  39     class Model;
  40     class EvaluationContext;
  41 }
  42 namespace com { namespace sun { namespace star {
  43     namespace xml {
  44         namespace xpath { class XXPathAPI; }
  45         namespace dom
  46         {
  47             class XNode;
  48             class XNodeList;
  49         }
  50     }
  51     namespace container { class XNameContainer; }
  52     namespace xforms { class XModel; }
  53     namespace xsd { class XDataType; }
  54 } } }
  55
  56 // includes for parent classes
  57 #include <cppuhelper/implbase8.hxx>
  58 #include <propertysetbase.hxx>
  59 #include <com/sun/star/form/binding/XValueBinding.hpp>
  60 #include <com/sun/star/form/binding/XListEntrySource.hpp>
  61 #include <com/sun/star/form/validation/XValidator.hpp>
  62 #include <com/sun/star/util/XModifyBroadcaster.hpp>
  63 #include <com/sun/star/container/XNamed.hpp>
  64 #include <com/sun/star/xml/dom/events/XEventListener.hpp>
  65 #include <com/sun/star/lang/XUnoTunnel.hpp>
  66 #include <com/sun/star/util/XCloneable.hpp>
  67
  68 // includes for member variables
  69 #include "pathexpression.hxx"
  70 #include "boolexpression.hxx"
  71 #include "mip.hxx"
  72 #include <rtl/ustring.hxx>
  73 #include <vector>
  74 #include <memory> // auto_ptr
  75
  76
  77
  78 namespace xforms
  79 {
  80
  81 /** An XForms Binding. Contains:
  82  *  # a connection to its model
  83  *  # an ID
  84  *  # an binding expression
  85  *  # model item properties
  86  *  # (NOT YET IMPLEMENTED) child bindings (sequence of)
  87  *
  88  * See http://www.w3.org/TR/xforms/ for more information.
  89  */
  90
  91 typedef cppu::ImplInheritanceHelper8<
  92     PropertySetBase,
  93     com::sun::star::form::binding::XValueBinding,
  94     com::sun::star::form::binding::XListEntrySource,
  95     com::sun::star::form::validation::XValidator,
  96     com::sun::star::util::XModifyBroadcaster,
  97     com::sun::star::container::XNamed,
  98     com::sun::star::xml::dom::events::XEventListener,
  99     com::sun::star::lang::XUnoTunnel,
 100     com::sun::star::util::XCloneable
 101 > Binding_t;
 102
 103 class Binding : public Binding_t
 104 {
 105 public:
 106     typedef com::sun::star::uno::Reference<com::sun::star::xforms::XModel> Model_t;
 107     typedef com::sun::star::uno::Reference<com::sun::star::util::XModifyListener> XModifyListener_t;
 108     typedef std::vector<XModifyListener_t> ModifyListeners_t;
 109     typedef com::sun::star::uno::Reference<com::sun::star::form::validation::XValidityConstraintListener> XValidityConstraintListener_t;
 110     typedef std::vector<XValidityConstraintListener_t> XValidityConstraintListeners_t;
 111     typedef com::sun::star::uno::Reference<com::sun::star::form::binding::XListEntryListener> XListEntryListener_t;
 112     typedef std::vector<XListEntryListener_t> XListEntryListeners_t;
 113     typedef com::sun::star::uno::Reference<com::sun::star::container::XNameContainer> XNameContainer_t;
 114     typedef com::sun::star::uno::Reference<com::sun::star::xml::dom::XNode> XNode_t;
 115     typedef com::sun::star::uno::Reference<com::sun::star::xml::dom::XNodeList> XNodeList_t;
 116     typedef com::sun::star::uno::Reference<com::sun::star::util::XCloneable> XCloneable_t;
 117     typedef com::sun::star::uno::Sequence<sal_Int8> IntSequence_t;
 118     typedef com::sun::star::uno::Sequence<rtl::OUString> StringSequence_t;
 119     typedef std::vector<MIP> MIPs_t;
 120     typedef std::vector<XNode_t> XNodes_t;
 121
 122
 123
 124 private:
 125
 126     /// the Model to which this Binding belongs; may be NULL
 127     Model_t mxModel;
 128
 129     /// binding-ID. A document-wide unique ID for this binding element.
 130     rtl::OUString msBindingID;
 131
 132     /// an XPath-expression to be instantiated on the data instance
 133     PathExpression maBindingExpression;
 134
 135     /// an XPath-expression to determine read-only status
 136     BoolExpression maReadonly;
 137
 138     /// an XPath-expression to determine relevance
 139     BoolExpression maRelevant;
 140
 141     /// an XPath-expression to determine if item is required
 142     BoolExpression maRequired;
 143
 144     /// an XPath-expression to determine if item is valid
 145     BoolExpression maConstraint;
 146
 147     /// user-readable explanation of the constraint
 148     rtl::OUString msExplainConstraint;
 149
 150     /// an XPath-expression to calculate values
 151     ComputedExpression maCalculate;
 152
 153     /// the XML namespaces used for XML names/XPath-expressions in this binding
 154     XNameContainer_t mxNamespaces;
 155
 156     /// a type name
 157     rtl::OUString msTypeName;
 158
 159     /// modify listeners
 160     ModifyListeners_t maModifyListeners;
 161
 162     /// list entry listener
 163     XListEntryListeners_t maListEntryListeners;
 164
 165     /// validity listeners;
 166     XValidityConstraintListeners_t maValidityListeners;
 167
 168     /// nodes on which we are listening for events
 169     XNodes_t maEventNodes;
 170
 171     /// the current MIP object for the first node we are bound to
 172     MIP maMIP;
 173
 174     /// flag to detect recursions in calculate
 175     bool mbInCalculate;
 176
 177     // flags to manage deferred notifications:
 178     /// if >0, valueModified() and bindingModified() will only set flags
 179     sal_Int32 mnDeferModifyNotifications;
 180     bool mbValueModified;   /// if true, valueModified needs to be called
 181     bool mbBindingModified; /// if true, bindingModified needs to be called
 182
 183
 184     void initializePropertySet();
 185
 186
 187 public:
 188     Binding();
 189     virtual ~Binding() throw();
 190
 191     //
 192     // property methods: get/set value
 193     //
 194
 195     Model_t getModel() const;   /// get XForms model
 196     void _setModel( const Model_t& ); /// set XForms model (only called by Model)
 197
 198
 199     rtl::OUString getModelID() const;   /// get ID of XForms model
 200
 201     rtl::OUString getBindingID() const;         /// get ID for this binding
 202     void setBindingID( const rtl::OUString& );  /// set ID for this binding
 203
 204     rtl::OUString getBindingExpression() const; /// get binding expression
 205     void setBindingExpression( const rtl::OUString& );  /// set binding exp.
 206
 207     // MIPs (model item properties)
 208
 209     rtl::OUString getReadonlyExpression() const;         /// get read-only MIP
 210     void setReadonlyExpression( const rtl::OUString& );  /// set read-only MIP
 211
 212     rtl::OUString getRelevantExpression() const;         /// get relevant MIP
 213     void setRelevantExpression( const rtl::OUString& );  /// set relevant MIP
 214
 215     rtl::OUString getRequiredExpression() const;         /// get required MIP
 216     void setRequiredExpression( const rtl::OUString& );  /// set required MIP
 217
 218     rtl::OUString getConstraintExpression() const;       /// get constraint MIP
 219     void setConstraintExpression( const rtl::OUString& );/// set constraint MIP
 220
 221     rtl::OUString getCalculateExpression() const;        /// get calculate MIP
 222     void setCalculateExpression( const rtl::OUString& ); /// set calculate MIP
 223
 224     rtl::OUString getType() const;         /// get type name MIP (static)
 225     void setType( const rtl::OUString& );  /// set type name MIP (static)
 226
 227     // a binding expression can only be interpreted with respect to
 228     // suitable namespace declarations. We collect those in the model and in a binding.
 229
 230     // access to a binding's namespace
 231     // (set-method only changes local namespaces (but may add to model))
 232     XNameContainer_t getBindingNamespaces() const;  /// set binding namespaces
 233     void setBindingNamespaces( const XNameContainer_t& ); /// get binding nmsp.
 234
 235     // access to the model's namespaces
 236     // (set-method changes model's namespaces (unless a local one is present))
 237     XNameContainer_t getModelNamespaces() const;  /// set model namespaces
 238     void setModelNamespaces( const XNameContainer_t& ); /// get model nmsp.
 239
 240
 241     // read-only properties that map MIPs to control data source properties
 242     bool getReadOnly() const;       // MIP readonly
 243     bool getRelevant() const;       // MIP relevant
 244     bool getExternalData() const;   // mapped from model's ExternalData property
 245
 246
 247     // missing binding properties:
 248     // - type (static; default: xsd:string)
 249     // - minOccurs/maxOccurs (computed XPath; default: 0/inf)
 250     // - p3ptype (static; no default)
 251
 252
 253
 254
 255     /// get this binding's context node
 256     xforms::EvaluationContext getEvaluationContext() const;
 257
 258     /// get evalation contexts for this binding's MIPs
 259     std::vector<xforms::EvaluationContext> getMIPEvaluationContexts();
 260
 261     /// get nodeset the bind is bound to
 262     XNodeList_t getXNodeList();
 263
 264     /// heuristically determine whether this binding is simple binding
 265     /// (here: simple binding == does not depend on other parts of the
 266     ///                          instance, it's not a 'dynamic' binding)
 267     bool isSimpleBinding() const;
 268
 269     /// heuristically determine whether this binding's binding
 270     /// expression is simple
 271     bool isSimpleBindingExpression() const;
 272
 273     /// update this binding (e.g. called by model for refresh )
 274     void update();
 275
 276     /// prevent change notifications being sent to controls
 277     void deferNotifications( bool );
 278
 279     /// is this binding valid? (are constraint, type and required MIPs ok?)
 280     bool isValid();
 281
 282     /// determine whether this binding currently performs a useful
 283     /// function, r whether is may be discarded
 284     bool isUseful();
 285
 286     /// explain why binding is invalid
 287     rtl::OUString explainInvalid();
 288
 289
 290     // the ID for XUnoTunnel calls
 291     static IntSequence_t getUnoTunnelID();
 292     static Binding* getBinding( const com::sun::star::uno::Reference<com::sun::star::beans::XPropertySet>& );
 293
 294     //
 295     // class-scoped typedef for easy-to-read UNO interfaces
 296     //
 297
 298     // basic types
 299     typedef com::sun::star::uno::Any Any_t;
 300     typedef com::sun::star::uno::Sequence<com::sun::star::uno::Type> Sequence_Type_t;
 301     typedef com::sun::star::uno::Type Type_t;
 302
 303     // reference types
 304     typedef com::sun::star::uno::Reference<com::sun::star::beans::XPropertyChangeListener> XPropertyChangeListener_t;
 305     typedef com::sun::star::uno::Reference<com::sun::star::beans::XPropertySetInfo> XPropertySetInfo_t;
 306     typedef com::sun::star::uno::Reference<com::sun::star::beans::XVetoableChangeListener> XVetoableChangeListener_t;
 307     typedef com::sun::star::uno::Reference<com::sun::star::xml::xpath::XXPathAPI> XXPathAPI_t;
 308     typedef com::sun::star::uno::Reference<com::sun::star::xml::dom::events::XEvent> XEvent_t;
 309     typedef com::sun::star::uno::Reference<com::sun::star::xsd::XDataType> XDataType_t;
 310
 311     // exceptions
 312     typedef com::sun::star::beans::PropertyVetoException PropertyVetoException_t;
 313     typedef com::sun::star::beans::UnknownPropertyException UnknownPropertyException_t;
 314     typedef com::sun::star::lang::IllegalArgumentException IllegalArgumentException_t;
 315     typedef com::sun::star::lang::NoSupportException NoSupportException_t;
 316     typedef com::sun::star::lang::WrappedTargetException WrappedTargetException_t;
 317     typedef com::sun::star::uno::RuntimeException RuntimeException_t;
 318     typedef com::sun::star::form::binding::IncompatibleTypesException IncompatibleTypesException_t;
 319     typedef com::sun::star::form::binding::InvalidBindingStateException InvalidBindingStateException_t;
 320     typedef com::sun::star::lang::NullPointerException NullPointerException_t;
 321     typedef com::sun::star::lang::IndexOutOfBoundsException IndexOutOfBoundsException_t;
 322
 323
 324
 325 private:
 326     /// check whether object is live, and throw suitable exception if not
 327     /// (to be used be API methods before acting on the object)
 328     void checkLive() throw( RuntimeException_t );
 329
 330     /// check whether binding has a model, and throw exception if not
 331     /// (to be used be API methods before acting on the object)
 332     void checkModel() throw( RuntimeException_t );
 333
 334     /// determine whether object is live
 335     /// live: has model, and model has been initialized
 336     bool isLive() const;
 337
 338     /// get the model implementation
 339     xforms::Model* getModelImpl() const;
 340     xforms::Model* getModelImpl( const Model_t& xModel ) const;
 341
 342     /// get MIP evaluation contexts
 343     /// (only valid if control has already been bound)
 344     std::vector<xforms::EvaluationContext> _getMIPEvaluationContexts() const;
 345
 346     /// bind this binding, and pre-compute the affected nodes
 347     void bind( bool bForceRebind = false );
 348
 349     /// the binding value has been changed:
 350     ///   trigger a modified event on all modified listeners
 351     void valueModified();
 352
 353     /// the binding itself has changed:
 354     ///   force rebind, then call valueModified()
 355     void bindingModified();
 356
 357
 358     /// register the event listeners for
 359     void registerListeners();
 360
 361     /// set MIPs defined by this binding on MIP item
 362     MIP getLocalMIP() const;
 363
 364     /// get the data type that applies to this binding
 365     XDataType_t getDataType();
 366
 367     /// determine whether binding is valid according to the given data type
 368     bool isValid_DataType();
 369
 370     /// explain validity of binding with respect to the given data type
 371     rtl::OUString explainInvalid_DataType();
 372
 373     /// 'clear' this binding - remove all listeners, etc.
 374     void clear();
 375
 376     /// distribute MIPs from current node recursively to childs
 377     void distributeMIP( const XNode_t &rxNode );
 378
 379     /// implement get*Namespaces()
 380     XNameContainer_t _getNamespaces() const;
 381
 382     /// implement set*Namespaces()
 383     void _setNamespaces( const XNameContainer_t&, bool bBinding );
 384
 385     /// set a useful default binding ID (if none is set)
 386     void _checkBindingID();
 387
 388 public:
 389     /// for debugging purposes only: get the MIPs defined by this binding
 390     const MIP* _getMIP();
 391
 392
 393
 394
 395
 396     //
 397     // XValueBinding:
 398     //
 399
 400 public:
 401
 402     virtual Sequence_Type_t SAL_CALL getSupportedValueTypes()
 403         throw( RuntimeException_t );
 404
 405     virtual sal_Bool SAL_CALL supportsType( const Type_t& aType )
 406         throw( RuntimeException_t );
 407
 408     virtual Any_t SAL_CALL getValue( const Type_t& aType )
 409         throw( IncompatibleTypesException_t,
 410                RuntimeException_t );
 411
 412     virtual void SAL_CALL setValue( const Any_t& aValue )
 413         throw( IncompatibleTypesException_t,
 414                InvalidBindingStateException_t,
 415                NoSupportException_t,
 416                RuntimeException_t );
 417
 418
 419
 420     //
 421     // XListEntry Source
 422     //
 423
 424     virtual sal_Int32 SAL_CALL getListEntryCount()
 425         throw( RuntimeException_t );
 426
 427     virtual rtl::OUString SAL_CALL getListEntry( sal_Int32 nPosition )
 428         throw( IndexOutOfBoundsException_t,
 429                RuntimeException_t );
 430
 431     virtual StringSequence_t SAL_CALL getAllListEntries()
 432         throw( RuntimeException_t );
 433
 434     virtual void SAL_CALL addListEntryListener( const XListEntryListener_t& )
 435         throw( NullPointerException_t,
 436                RuntimeException_t );
 437
 438     virtual void SAL_CALL removeListEntryListener( const XListEntryListener_t&)
 439         throw( NullPointerException_t,
 440                RuntimeException_t );
 441
 442
 443
 444     //
 445     // XValidator:
 446     //
 447
 448     virtual sal_Bool SAL_CALL isValid(
 449         const Any_t& )
 450         throw( RuntimeException_t );
 451
 452     virtual rtl::OUString SAL_CALL explainInvalid(
 453         const Any_t& )
 454         throw( RuntimeException_t );
 455
 456     virtual void SAL_CALL addValidityConstraintListener(
 457         const XValidityConstraintListener_t& xListener )
 458         throw( NullPointerException_t,
 459                RuntimeException_t );
 460
 461     virtual void SAL_CALL removeValidityConstraintListener(
 462         const XValidityConstraintListener_t& xListener )
 463         throw( NullPointerException_t,
 464                RuntimeException_t );
 465
 466
 467     //
 468     // XModifyBroadcaster & friends:
 469     //   inform listeners about changes in our values
 470     //
 471
 472 public:
 473
 474     virtual void SAL_CALL addModifyListener(
 475         const XModifyListener_t& xListener )
 476         throw( RuntimeException_t );
 477
 478     virtual void SAL_CALL removeModifyListener(
 479         const XModifyListener_t& xListener )
 480         throw( RuntimeException_t );
 481
 482
 483
 484
 485     //
 486     // XNamed:
 487     //   get/set name
 488     //
 489
 490 public:
 491
 492     virtual rtl::OUString SAL_CALL getName()
 493         throw( RuntimeException_t );
 494
 495     virtual void SAL_CALL setName( const rtl::OUString& )
 496         throw( RuntimeException_t );
 497
 498
 499
 500     //
 501     // xml::dom::event::XEventListener
 502     //   receive an event if our node changed
 503     //
 504
 505     virtual void SAL_CALL handleEvent(
 506         const XEvent_t& xEvent )
 507         throw( RuntimeException_t );
 508
 509
 510
 511     //
 512     // XUnoTunnel
 513     //
 514
 515     virtual sal_Int64 SAL_CALL getSomething( const IntSequence_t& )
 516         throw( RuntimeException_t );
 517
 518
 519     //
 520     // XCloneable
 521     //
 522
 523     virtual XCloneable_t SAL_CALL createClone()
 524         throw( RuntimeException_t );
 525 };
 526
 527
 528 } // namespace xforms
 529
 530 #endif