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