diff options
Diffstat (limited to 'framework/source/inc/loadenv')
| -rw-r--r-- | framework/source/inc/loadenv/actionlockguard.hxx | 209 | ||||
| -rw-r--r-- | framework/source/inc/loadenv/loadenv.hxx | 704 | ||||
| -rw-r--r-- | framework/source/inc/loadenv/loadenvexception.hxx | 197 | ||||
| -rw-r--r-- | framework/source/inc/loadenv/targethelper.hxx | 124 |
4 files changed, 1234 insertions, 0 deletions
diff --git a/framework/source/inc/loadenv/actionlockguard.hxx b/framework/source/inc/loadenv/actionlockguard.hxx new file mode 100644 index 000000000000..2059c976ecae --- /dev/null +++ b/framework/source/inc/loadenv/actionlockguard.hxx @@ -0,0 +1,209 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __FRAMEWORK_LOADENV_ACTIONLOCKGUARD_HXX_ +#define __FRAMEWORK_LOADENV_ACTIONLOCKGUARD_HXX_ + +//_______________________________________________ +// includes of own project + +#include <threadhelp/threadhelpbase.hxx> +#include <threadhelp/resetableguard.hxx> + +//_______________________________________________ +// includes of uno interface +#include <com/sun/star/document/XActionLockable.hpp> + +//_______________________________________________ +// includes of an other project + +//_______________________________________________ +// namespace + +namespace framework{ + +#ifndef css +namespace css = ::com::sun::star; +#endif + +//_______________________________________________ +// definitions + +/** @short implements a guard, which can use the interface + <type scope="com::sun::star::document">XActionLockable</type>. + + @descr This guard should be used to be shure, that any lock will be + released. Otherwhise the locaked document can hinder the office on shutdown! +*/ +class ActionLockGuard : private ThreadHelpBase +{ + //------------------------------------------- + // member + + private: + + /** @short points to the object, which can be locked from outside. */ + css::uno::Reference< css::document::XActionLockable > m_xActionLock; + + /** @short knows if a lock exists on the internal lock object + forced by this guard instance. */ + sal_Bool m_bActionLocked; + + //------------------------------------------- + // interface + + public: + + //--------------------------------------- + /** @short default ctor to initialize a "non working guard". + + @descr That can be usefull in cases, where no resource still exists, + but will be available next time. Then this guard can be used + in a mode "use guard for more then one resources". + */ + ActionLockGuard() + : ThreadHelpBase ( ) + , m_bActionLocked(sal_False) + { + } + + //--------------------------------------- + /** @short initialize new guard instance and lock the given resource immediatly. + + @param xLock + points to the outside resource, which should be locked. + */ + ActionLockGuard(const css::uno::Reference< css::document::XActionLockable >& xLock) + : ThreadHelpBase ( ) + , m_bActionLocked(sal_False) + { + setResource(xLock); + } + + //--------------------------------------- + /** @short release this guard instance and make shure, that no lock + will exist afterwards on the internal wrapped resource. + */ + virtual ~ActionLockGuard() + { + unlock(); + } + + //--------------------------------------- + /** @short set a new resource for locking at this guard. + + @descr This call will fail, if an internal resource already exists + and is currently locked. + + @param xLock + points to the outside resource, which should be locked. + + @return sal_True, if new resource could be set and locked. + sal_False otherwhise. + */ + virtual sal_Bool setResource(const css::uno::Reference< css::document::XActionLockable >& xLock) + { + // SAFE -> .......................... + ResetableGuard aMutexLock(m_aLock); + + if (m_bActionLocked || !xLock.is()) + return sal_False; + + m_xActionLock = xLock; + m_xActionLock->addActionLock(); + m_bActionLocked = m_xActionLock->isActionLocked(); + // <- SAFE .......................... + + return sal_True; + } + + //--------------------------------------- + /** @short set a new resource for locking at this guard. + + @descr This call will fail, if an internal resource already exists + and is currently locked. + + @param xLock + points to the outside resource, which should be locked. + + @return sal_True, if new resource could be set and locked. + sal_False otherwhise. + */ + virtual void freeResource() + { + // SAFE -> .......................... + ResetableGuard aMutexLock(m_aLock); + + css::uno::Reference< css::document::XActionLockable > xLock = m_xActionLock ; + sal_Bool bLocked = m_bActionLocked; + + m_xActionLock.clear(); + m_bActionLocked = sal_False; + + aMutexLock.unlock(); + // <- SAFE .......................... + + if (bLocked && xLock.is()) + xLock->removeActionLock(); + } + + //--------------------------------------- + /** @short lock the internal wrapped resource, if its not already done. */ + virtual void lock() + { + // SAFE -> .......................... + ResetableGuard aMutexLock(m_aLock); + + if (!m_bActionLocked && m_xActionLock.is()) + { + m_xActionLock->addActionLock(); + m_bActionLocked = m_xActionLock->isActionLocked(); + } + // <- SAFE .......................... + } + + //--------------------------------------- + /** @short unlock the internal wrapped resource, if its not already done. */ + virtual void unlock() + { + // SAFE -> .......................... + ResetableGuard aMutexLock(m_aLock); + + if (m_bActionLocked && m_xActionLock.is()) + { + m_xActionLock->removeActionLock(); + // dont check for any locks here ... + // May another guard use the same lock object :-( + m_bActionLocked = sal_False; + } + // <- SAFE .......................... + } +}; + +} // namespace framework + +#endif // __FRAMEWORK_LOADENV_ACTIONLOCKGUARD_HXX_ diff --git a/framework/source/inc/loadenv/loadenv.hxx b/framework/source/inc/loadenv/loadenv.hxx new file mode 100644 index 000000000000..6330f2598605 --- /dev/null +++ b/framework/source/inc/loadenv/loadenv.hxx @@ -0,0 +1,704 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ +#ifndef __FRAMEWORK_LOADENV_LOADENV_HXX_ +#define __FRAMEWORK_LOADENV_LOADENV_HXX_ + +//_______________________________________________ +// includes of own project + +#include <loadenv/loadenvexception.hxx> +#include <loadenv/actionlockguard.hxx> +#include <threadhelp/threadhelpbase.hxx> + +//_______________________________________________ +// includes of uno interface +#include <com/sun/star/lang/XMultiServiceFactory.hpp> +#include <com/sun/star/frame/XComponentLoader.hpp> +#include <com/sun/star/frame/XFrameLoader.hpp> +#include <com/sun/star/frame/XLoadEventListener.hpp> +#include <com/sun/star/frame/XDispatchResultListener.hpp> +#include <com/sun/star/frame/XFrame.hpp> +#include <com/sun/star/util/URL.hpp> + +#ifndef _COM_SUN_STAR_LANG_IllegalArgumentException_HPP_ +#include <com/sun/star/lang/IllegalArgumentException.hpp> +#endif + +#ifndef _COM_SUN_STAR_IO_IOException_HPP_ +#include <com/sun/star/io/IOException.hpp> +#endif + +//_______________________________________________ +// includes of an other project +#include <comphelper/mediadescriptor.hxx> +#include <comphelper/sequenceashashmap.hxx> +#include <cppuhelper/implbase2.hxx> + +//_______________________________________________ +// namespace + +namespace framework{ + +namespace css = ::com::sun::star; +class QuietInteraction; +//_______________________________________________ +// definitions + +/** @short implements general mechainsm for loading documents. + + @descr An instance of this class can be used inside the API calls + XComponentLoader::loadComponentFromURL() and XDispatch::dispatch() + (of course in its derived interfaces too :-)). + + @author as96863 + */ +class LoadEnv : private ThreadHelpBase +{ + //___________________________________________ + // structs, types, etc. + + public: + + /** @short enable/disable special features + of a load request. + + @desrc Such features must outcome without + any special parameters. + To make enableing/disabling of + features very easy (e.g. at the ctor of + this class) these values must be combinable + as flags. That means: its values must be in + range of [2^n]! + */ + enum EFeature + { + /// we should be informed, if no feature is enabled :-) + E_NO_FEATURE = 0, + /// enable using of UI elements during loading (means progress, interaction handler etcpp.) + E_WORK_WITH_UI = 1, + /// enable loading of resources, which are not related to a target frame! (see concept of ContentHandler) + E_ALLOW_CONTENTHANDLER = 2 + }; + + //_______________________________________ + + /** @short classify a content. + + @descr The load environment must know, if a content + is related to a target frame or not. Only "visible" + components, which full fill the requirements of the + model-controller-view paradigm can be loaded into a frame. + Such contents are classified as E_CAN_BE_LOADED. + + But e.g. for the dispatch framework exists special ContentHandler + objects, which can load a content in "non visible" mode ... + and do not need a target frame for its operation. Such + ContentHandler e.g. plays sounds. + Such contents are classified as E_CAN_BE_HANDLED. + + And last but not least a content can be "not valid" in general. + */ + enum EContentType + { + /// identifies a content, which seems to be invalid in general + E_UNSUPPORTED_CONTENT, + /// identifies a content, which can be used with a ContentHandler and is not related to a target frame + E_CAN_BE_HANDLED, + /// identifies a content, which can be loaded into a target frame + E_CAN_BE_LOADED, + /// special mode for non real loading, In such case the model is given directly! + E_CAN_BE_SET + }; + + //___________________________________________ + // member + + private: + + /** @short reference to an uno service manager, which must be used + to created on needed services on demand. + */ + css::uno::Reference< css::lang::XMultiServiceFactory > m_xSMGR; + + /** @short points to the frame, which uses this LoadEnv object + and must be used to start target search there. + */ + css::uno::Reference< css::frame::XFrame > m_xBaseFrame; + + /** @short points to the frame, into which the new component was loaded. + + @descr Note: This reference will be empty if loading failed + or a non visible content was loaded! + It can be the same frame as m_xBaseFrame it describe, in case + the target "_self", "" or the search flag "SELF" was used. + Otherwhise its the new created or recycled frame, which was + used for loading and contains further the new component. + + Please use method getTarget() or getTargetComponent() + to return the frame/controller or model to any interested + user of the results of this load request. + */ + css::uno::Reference< css::frame::XFrame > m_xTargetFrame; + + /** @short contains the name of the target, in which the specified resource + of this instance must be loaded. + */ + ::rtl::OUString m_sTarget; + + /** @short if m_sTarget is not a special one, this flags regulate searching + of a suitable one. + */ + sal_Int32 m_nSearchFlags; + + /** @short contains all needed informations about the resource, + which should be loaded. + + @descr Inside this struct e.g. the URL, its type and filter name, + the stream or a model directly are saved. + */ + ::comphelper::MediaDescriptor m_lMediaDescriptor; + + /** @short because the mediadescriptor contains the complete URL ... but + some functionality need the structured version, we hold it twice :-(. + */ + css::util::URL m_aURL; + + /** @short enable/disable special features of a load request. */ + EFeature m_eFeature; + + /** @short classify the content, which should be loaded by this instance. */ + EContentType m_eContentType; + + /** @short it indicates, that the member m_xTargetFrame was new created for this + load request and must be closed in case loading (not handling!) + operation failed. The default value is sal_False! + */ + sal_Bool m_bCloseFrameOnError; + + /** @short it indicates, that the old document (which was located inside m_xBaseFrame + in combination with the m_sTarget value "_self") was suspended. + Normaly it will be replaced by the new loaded document. But in case + loading (not handling!) failed, it must be reactivated. + The default value is sal_False! + */ + sal_Bool m_bReactivateControllerOnError; + + /** @short it holds one (!) asynchronous used contenthandler or frameloader + alive, till the asynchronous operation will be finished. + */ + css::uno::Reference< css::uno::XInterface > m_xAsynchronousJob; + + /** @short holds the information about the finished load process. + + @descr The content of m_xTargetFrame cant be used as valid indicator, + (in case the micht existing old document was reactivated) + we must hold the result of the load process explicitly. + */ + sal_Bool m_bLoaded; + + /** @short holds an XActionLock on the internal used task member. + + @seealso m_xTargetFrame + */ + ActionLockGuard m_aTargetLock; + + /** TODO document me ... */ + void* m_pCheck; + + QuietInteraction* m_pQuietInteraction; + + //___________________________________________ + // native interface + + public: + + /** @short initialize a new instance of this load environment. + + @param xSMGR + reference to an uno service manager, which can be used internaly + to create on needed services on demand. + + @throw Currently there is no reason to throw such exception! + + @throw A RuntimeException in case any internal process indicates, that + the whole runtime cant be used any longer. + */ + LoadEnv(const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR) + throw(LoadEnvException, css::uno::RuntimeException); + + //_______________________________________ + + /** @short deinitialize an instance of this class in the right way. + */ + virtual ~LoadEnv(); + + //_______________________________________ + + /** @short DRAFT TODO + */ + static css::uno::Reference< css::lang::XComponent > loadComponentFromURL(const css::uno::Reference< css::frame::XComponentLoader >& xLoader, + const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR , + const ::rtl::OUString& sURL , + const ::rtl::OUString& sTarget, + sal_Int32 nFlags , + const css::uno::Sequence< css::beans::PropertyValue >& lArgs ) + throw(css::lang::IllegalArgumentException, + css::io::IOException , + css::uno::RuntimeException ); + + //_______________________________________ + + /** @short set some changeable parameters for a new load request. + + @descr The parameter for targeting, the content description, and + some environment specifier (UI, dispatch functionality) + can be set here ... BEFORE the real load process is started + by calling startLoading(). Of course a still running load request + will be detected here and a suitable exception will be thrown. + Such constellation can be detected outside by using provided + synchronisation methods or callbacks. + + @param sURL + points to the resource, which should be loaded. + + @param lMediaDescriptor + contains additional informations for the following load request. + + @param xBaseFrame + points to the frame which must be used as start point for target search. + + @param sTarget + regulate searching/creating of frames, which should contain the + new loaded component afterwards. + + @param nSearchFlags + regulate searching of targets, if sTarget is not a special one. + + @param eFeature + flag field, which enable/disable special features of this + new instance for following load call. + + @param eContentType + classify the given content. + This value is set to a default value "UNKNWON_CONTENT", which force + an internal check, if this content is loadable or not. + But may this check was already made by the caller of this method and + passing this information to this LoadEnv instance can supress this + might expensive check. + That can be usefull in case this information is needed outside too, + to decide if its neccessary to create some resources for this load + request ... or to reject the request imidiatly if it seems to be not + loadable in general. + + @throw A LoadEnvException e.g. if another load operation is till in progress + or initialization of a new one fail by other reasons. + The real reason, a suitable message and ID will be given here immidiatly. + + @throw A RuntimeException in case any internal process indicates, that + the whole runtime cant be used any longer. + */ + virtual void initializeLoading(const ::rtl::OUString& sURL , + const css::uno::Sequence< css::beans::PropertyValue >& lMediaDescriptor, + const css::uno::Reference< css::frame::XFrame >& xBaseFrame , + const ::rtl::OUString& sTarget , + sal_Int32 nSearchFlags , + EFeature eFeature = E_NO_FEATURE , + EContentType eContentType = E_UNSUPPORTED_CONTENT) + throw(LoadEnvException, css::uno::RuntimeException); + + //_______________________________________ + + /** @short start loading of the resource represented by this loadenv instance. + + @descr There is no direct return value possible here. Because it depends + from the usage of this instance! E.g. for loading a "visible component" + a frame with a controller/model inside can be possible. For loading + of a "non visible component" only an information about a successfully start + can be provided. + Further it cant be guranteed, that the internal process runs synchronous. + Thats why we preferr using of specialized methods afterwards e.g. to: + - wait till the internal job will be finished + and get the results + - or to let it run without any further control from outside. + + @throw A LoadEnvException if start of the load process failed (because + another is still in progress!). + The reason, a suitable message and ID will be given here immidiatly. + + @throw A RuntimeException in case any internal process indicates, that + the whole runtime cant be used any longer. + */ + virtual void startLoading() + throw(LoadEnvException, css::uno::RuntimeException); + + //_______________________________________ + + /** @short wait for an alreay running load request (started by calling + startLoading() before). + + @descr The timeout parameter can be used to wait some times only + or forever. The return value indicates if the load request + was finished during the specified timeout period. + But it indicates not, if the load request was successfully or not! + + @param nTimeout + specify a timeout in [ms]. + A value 0 let it wait forever! + + @return sal_True if the started load process could be finished in time; + sal_False if the specified time was over. + + @throw ... currently not used :-) + + @throw A RuntimeException in case any internal process indicates, that + the whole runtime cant be used any longer. + */ + virtual sal_Bool waitWhileLoading(sal_uInt32 nTimeout = 0) + throw(LoadEnvException, css::uno::RuntimeException); + + //_______________________________________ + /** TODO document me ... */ + virtual void cancelLoading() + throw(LoadEnvException, css::uno::RuntimeException); + + //_______________________________________ + /** TODO document me ... */ + virtual css::uno::Reference< css::frame::XFrame > getTarget() const; + + //_______________________________________ + /** TODO document me ... */ + virtual css::uno::Reference< css::lang::XComponent > getTargetComponent() const; +/* + //___________________________________________ + // helper uno interface! + // You have to use the native interface only! + + public: + + //_______________________________________ + // frame.XLoadEventListener + virtual void SAL_CALL loadFinished(const css::uno::Reference< css::frame::XFrameLoader >& xLoader) + throw(css::uno::RuntimeException); + + virtual void SAL_CALL loadCancelled(const css::uno::Reference< css::frame::XFrameLoader >& xLoader) + throw(css::uno::RuntimeException); + + //_______________________________________ + // frame.XDispatchResultListener + virtual void SAL_CALL dispatchFinished(const css::frame::DispatchResultEvent& aEvent) + throw(css::uno::RuntimeException); + + //_______________________________________ + // lang.XEventListener + virtual void SAL_CALL disposing(const css::lang::EventObject& aEvent) + throw(css::uno::RuntimeException); +*/ + + //___________________________________________ + // static interface + + public: + + /** @short checks if the specified content can be handled by a + ContentHandler only and is not related to a target frame, + or if it can be loaded by a FrameLoader into a target frame + as "visible" component. + + @descr using: + switch(classifyContent(...)) + { + case E_CAN_BE_HANDLED : + handleIt(...); + break; + + case E_CAN_BE_LOADED : + xFrame = locateTargetFrame(); + loadIt(xFrame); + break; + + case E_NOT_A_CONTENT : + default : throw ...; + } + + @param sURL + describe the content. + + @param lMediaDescriptor + describe the content more detailed! + + @return A suitable enum value, which classify the specified content. + */ + static EContentType classifyContent(const ::rtl::OUString& sURL , + const css::uno::Sequence< css::beans::PropertyValue >& lMediaDescriptor); + + /** TODO document me ... */ + static void initializeUIDefaults( + const css::uno::Reference< css::lang::XMultiServiceFactory >& i_rSMGR, + ::comphelper::MediaDescriptor& io_lMediaDescriptor, + const bool _bUIMode, + QuietInteraction** o_ppQuiteInteraction + ); + + /** TODO document me ... */ + void impl_setResult(sal_Bool bResult); + + /** TODO document me ... */ + css::uno::Reference< css::uno::XInterface > impl_searchLoader(); + + //_______________________________________ + + /** @short it means; show the frame, bring it to front, + might set the right icon etcpp. in case loading was + successfully or reactivate a might existing old document or + close the frame if it was created before in case loading failed. + + @throw A LoadEnvException only in cases, where an internal error indicates, + that the complete load environment seems to be not useable in general. + In such cases a RuntimeException would be to hard for the outside code :-) + + @throw A RuntimeException in case any internal process indicates, that + the whole runtime cant be used any longer. + */ + void impl_reactForLoadingState() + throw(LoadEnvException, css::uno::RuntimeException); + + //___________________________________________ + // private helper + + private: + + /** @short tries to detect the type and the filter of the specified content. + + @descr This method update the available media descriptor of this instance, + so it contains the right type, a corresponding filter, may a + valid frame loader etc. In case detection failed, this descriptor + is corrected first, before a suitable exception will be thrown. + (Excepting a RuntimeException occure!) + + @attention Not all types we know, are supported by filters. So it does not + indicates an error, if no suitable filter(loader etcpp will be found + for a type. But a type must be detected for the specified content. + Otherwhise its an error and loading cant be finished successfully. + + @throw A LoadEnvException if detection failed. + + @throw A RuntimeException in case any internal process indicates, that + the whole runtime cant be used any longer. + */ + void impl_detectTypeAndFilter() + throw(LoadEnvException, css::uno::RuntimeException); + + //_______________________________________ + + /** @short tries to ask user for it's filter decision in case + normal detection failed. + + @descr We use a may existing interaction handler to do so. + + @return [string] + the type selected by the user. + + @attention Internaly we update the member m_lMediaDescriptor! + */ + ::rtl::OUString impl_askUserForTypeAndFilterIfAllowed() + throw(LoadEnvException, css::uno::RuntimeException); + + //_______________________________________ + + /** @short tries to use ContentHandler objects for loading. + + @descr It searches for a suitable content handler object, registered + for the detected content type (must be done before by calling + impl_detectTypeAndFilter()). Because such handler does not depend + from a real target frame, location of such frame will be + supressed here. + In case handle failed all new created resources will be + removed before a suitable exception is thrown. + (Excepting a RuntimeException occure!) + + @return TODO + + @throw A LoadEnvException if handling failed. + + @throw A RuntimeException in case any internal process indicates, that + the whole runtime cant be used any longer. + */ + sal_Bool impl_handleContent() + throw(LoadEnvException, css::uno::RuntimeException); + + //_______________________________________ + + /** @short tries to use FrameLoader objects for loading. + + @descr First the target frame will be located. If it could be found + or new created a filter/frame loader will be instanciated and + used to load the content into this frame. + In case loading failed all new created resources will be + removed before a suitable exception is thrown. + (Excepting a RuntimeException occure!) + + @return TODO + + @throw A LoadEnvException if loading failed. + + @throw A RuntimeException in case any internal process indicates, that + the whole runtime cant be used any longer. + */ + sal_Bool impl_loadContent() + throw(LoadEnvException, css::uno::RuntimeException); + + //_______________________________________ + + /** @short checks if the specified content is already loaded. + + @descr It depends from the set target information, if such + search is allowed or not! So this method checks first, + if the target is the special one "_default". + If not it returns with an empty result immidatly! + In case search is allowed, an existing document with the + same URL is searched. If it could be found, the corresponding + view will get the focus and this method return the corresponding frame. + Optional jumpmarks will be accepted here too. So the + view of the document will be updated to show the position + inside the document, which is related to the jumpmark. + + @return A valid reference to the target frame, which contains the already loaded content + and could be activated successfully. An empty reference oterwhise. + + @throw A LoadEnvException only in cases, where an internal error indicates, + that the complete load environment seems to be not useable in general. + In such cases a RuntimeException would be to hard for the outside code :-) + + @throw A RuntimeException in case any internal process indicates, that + the whole runtime cant be used any longer. + */ + css::uno::Reference< css::frame::XFrame > impl_searchAlreadyLoaded() + throw(LoadEnvException, css::uno::RuntimeException); + + //_______________________________________ + + /** @short search for any target frame, which seems to be useable + for this load request. + + @descr Because this special feature is bound to the target specifier "_default" + its checked inside first. If its not set => this method return an empty + reference. Otherwhise any currently existing frame will be analyzed, if + it can be used here. The following rules exists: + + <ul> + <li>The frame must be empty ...</li> + <li>or contains an empty document of the same application module + which the new document will have (Note: the filter of the new content + must be well known here!)</li> + <li>and(!) this target must not be already used by any other load request.</li> + </ul> + + If a suitable target is located it will be locked. Thats why the last rule + exists! If this method returns a valid frame reference, it was locked to be useable + for this load request only. (Dont forget to reset this state later!) + Concurrent LoadEnv instances can synchronize her work be using such locks :-) HOPEFULLY + + @throw A LoadEnvException only in cases, where an internal error indicates, + that the complete load environment seems to be not useable in general. + In such cases a RuntimeException would be to hard for the outside code :-) + + @throw A RuntimeException in case any internal process indicates, that + the whole runtime cant be used any longer. + */ + css::uno::Reference< css::frame::XFrame > impl_searchRecycleTarget() + throw(LoadEnvException, css::uno::RuntimeException); + + //_______________________________________ + + /** @short because showing of a frame is needed more then once ... + it's implemented as an seperate method .-) + + @descr Note: Showing of a frame is bound to a special feature ... + a) If we recycle any existing frame, we must bring it to front. + Showing of such frame isnt needed realy .. because we recycle + visible frames only! + b) If the document was already shown (e.g. by our progress implementation) + we do nothing here. The reason behind: The document was already shown .. + and it was already make a top window ... + If the user activated another frame inbetween (because loading needed some time) + it's not allowed to disturb the user again. Then the frame must resists in the background. + c) If the frame was not shown before ... but loading of a visible document into this frame + was finished ... we need both actions: setVisible() and toFront(). + + @param xWindow + points to the container window of a frame. + + @param bForceToFront + if it's set to sal_False ... showing of the window is done more intelligent. + setVisible() is called only if the window was not shown before. + This mode is needed by b) and c) + If it's set to sal_True ... both actions has to be done: setVisible(), toFront()! + This mode is needed by a) + */ + void impl_makeFrameWindowVisible(const css::uno::Reference< css::awt::XWindow >& xWindow , + sal_Bool bForceToFront); + + //_______________________________________ + + /** @short checks weather a frame is already used for another load request or not. + + @descr Such frames cant be used for our "recycle feature"! + + @param xFrame + the frame, which should be checked. + + @return [sal_Bool] + sal_True if this frame is already used for loading, + sal_False otherwise. + */ + sal_Bool impl_isFrameAlreadyUsedForLoading(const css::uno::Reference< css::frame::XFrame >& xFrame) const; + + //_______________________________________ + + /** @short try to determine the used application module + of this load request and applay right position and size + for this document window ... hopefully before we show it .-) + */ + void impl_applyPersistentWindowState(const css::uno::Reference< css::awt::XWindow >& xWindow); + + //_______________________________________ + + /** @short determine if it's allowed to open new document frames. + */ + sal_Bool impl_furtherDocsAllowed(); + + //_______________________________________ + + /** @short jumps to the requested bookmark inside a given document. + */ + void impl_jumpToMark(const css::uno::Reference< css::frame::XFrame >& xFrame, + const css::util::URL& aURL ); +}; + +} // namespace framework + +#endif // __FRAMEWORK_LOADENV_LOADENV_HXX_ diff --git a/framework/source/inc/loadenv/loadenvexception.hxx b/framework/source/inc/loadenv/loadenvexception.hxx new file mode 100644 index 000000000000..bb26e98f4695 --- /dev/null +++ b/framework/source/inc/loadenv/loadenvexception.hxx @@ -0,0 +1,197 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __FRAMEWORK_LOADENV_LOADENVEXCEPTION_HXX_ +#define __FRAMEWORK_LOADENV_LOADENVEXCEPTION_HXX_ + +//_______________________________________________ +// includes of own project + +//_______________________________________________ +// includes of uno interface + +#include <com/sun/star/uno/Any.h> +#include <com/sun/star/uno/Exception.hpp> + +//_______________________________________________ +// includes of an other project +#include <rtl/string.hxx> + +//_______________________________________________ +// namespace + +namespace framework{ + +#ifndef css // conflict with define :-( +namespace css = ::com::sun::star; +#endif + +//_______________________________________________ +// definitions + +/** @short specify an exception, which can be used inside the + load environment only. + + @descr Of course outside code must wrapp it, to transport + the occured information to its caller. + + @author as96863 + */ +class LoadEnvException +{ + //___________________________________________ + // const + + public: + + /** @short Can be used as an ID for an instance of a LoadEnvException. + @descr To prevent errors on adding/removing/changing such IDs here, + an enum field is used. Its int values are self organized ... + */ + enum EIDs + { + /** @short The specified URL/Stream/etcpp. can not be handled by a LoadEnv instance. */ + ID_UNSUPPORTED_CONTENT, + + /** @short It was not possible to get access to global filter configuration. + @descr Might som neccsessary services could not be created. */ + ID_NO_CONFIG_ACCESS, + + /** @short Some data obtained from the filter configuration seems to incorrect. + @descr Might a filter-type relation ship seem to be damaged. */ + ID_INVALID_FILTER_CONFIG, + + /** @short indicates a corrupted media descriptor. + @descr Some parts are required - some other ones are optional. Such exception + should be thrown, if a required item does not exists. */ + ID_INVALID_MEDIADESCRIPTOR, + + /** @short Its similar to an uno::RuntimeException .... + @descr But such runtime exception can break the whole office code. + So its capsulated to this specialized load environment only. + Mostly it indicates a missing but needed resource ... e.g the + global desktop reference! */ + ID_INVALID_ENVIRONMENT, + + /** @short indicates a failed search for the right target frame. */ + ID_NO_TARGET_FOUND, + + /** @short An already existing document was found inside a target frame. + But its controller could not be suspended successfully. Thats + why the new load request was cancelled. The document could not + be replaced. */ + ID_COULD_NOT_SUSPEND_CONTROLLER, + + /** @short TODO */ + ID_COULD_NOT_REACTIVATE_CONTROLLER, + + /** @short inidcates an already running load operation. Of yourse the same + instance cant be used for multiple load requests at the same time. + */ + ID_STILL_RUNNING, + + /** @short sometiems we cant specify the reason for an error, because we + was interrupted by an called code in an unexpected way ... + */ + ID_GENERAL_ERROR + }; + + //___________________________________________ + // member + + public: + + /** @short contains a suitable message, which describes the reason for this + exception. */ + ::rtl::OString m_sMessage; + + /** @short An ID, which make this exception unique among others. */ + sal_Int32 m_nID; + + /** @short Contains the original exception, if any occured. */ + css::uno::Any m_exOriginal; + + /** TODO + Experimental use! May it can be usefully to know, if an exception was already + catched and handled by an interaction and was might be rethrowed! */ + sal_Bool m_bHandled; + + //___________________________________________ + // interface + + public: + + /** @short initialize a new instance with an ID. + @descr Some other items of this exception + (e.g. a suitable message) will be generated + automaticly. + + @param nID + One of the defined const IDs of this class. + */ + LoadEnvException(sal_Int32 nID) + { + m_nID = nID; + } + + //_______________________________________ + + /** @short initialize a new instance with an ID + an wrap a detected exception into this one. + @descr Some other items of this exception + (e.g. a suitable message) will be generated + automaticly. + + @param nID + One of the defined const IDs of this class. + + @param exUno + the original catched uno exception. + */ + LoadEnvException( sal_Int32 nID , + const css::uno::Any& exUno) + { + m_nID = nID ; + m_exOriginal = exUno; + } + + //_______________________________________ + + /** @short destruct an instance of this exception. + */ + ~LoadEnvException() + { + m_sMessage = ::rtl::OString(); + m_nID = 0; + m_bHandled = false; + m_exOriginal.clear(); + } +}; + +} // namespace framework + +#endif // __FRAMEWORK_LOADENV_LOADENVEXCEPTION_HXX_ diff --git a/framework/source/inc/loadenv/targethelper.hxx b/framework/source/inc/loadenv/targethelper.hxx new file mode 100644 index 000000000000..179ec117ab19 --- /dev/null +++ b/framework/source/inc/loadenv/targethelper.hxx @@ -0,0 +1,124 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __FRAMEWORK_TARGETHELPER_HXX_ +#define __FRAMEWORK_TARGETHELPER_HXX_ + +//_______________________________________________ +// own includes + +#include <sal/types.h> +#include <rtl/ustring.hxx> +#include <targets.h> +//_______________________________________________ +// namespace + +namespace framework{ + +//_______________________________________________ +// definitions + +/** @short can be used to detect, if a target name (used e.g. for XFrame.findFrame()) + has a special meaning or can be used as normal frame name (e.g. for XFrame.setName()). + + @author as96863 + */ +class TargetHelper +{ + //___________________________________________ + // const + + public: + + /** @short its used at the following interfaces to classify + target names. + */ + enum ESpecialTarget + { + E_NOT_SPECIAL , + E_SELF , + E_PARENT , + E_TOP , + E_BLANK , + E_DEFAULT , + E_BEAMER , + E_MENUBAR , + E_HELPAGENT , + E_HELPTASK + }; + + //___________________________________________ + // interface + + public: + + //___________________________________________ + + /** @short it checks the given unknown target name, + if it's the expected special one. + + @note An empty target is similar to "_self"! + + @param sCheckTarget + must be the unknwon target name, which should be checked. + + @param eSpecialTarget + represent the expected target. + + @return It returns <TRUE/> if <var>sCheckTarget</var> represent + the expected <var>eSpecialTarget</var> value; <FALSE/> otherwhise. + */ + static sal_Bool matchSpecialTarget(const ::rtl::OUString& sCheckTarget , + ESpecialTarget eSpecialTarget); + + //___________________________________________ + + /** @short it checks, if the given name can be used + to set it at a frame using XFrame.setName() method. + + @descr Because we handle special targets in a hard coded way + (means we do not check the real name of a frame then) + such named frames will never be found! + + And in case such special names can exists one times only + by definition inside the same frame tree (e.g. _beamer and + OFFICE_HELP_TASK) its not a good idea to allow anything here :-) + + Of course we can't check unknwon names, which are not special ones. + But we decide, that it's not allowed to use "_" as first sign + (because we reserve this letter for our own purposes!) + and the value must not a well known special target. + + @param sName + the new frame name, which sould be checked. + */ + static sal_Bool isValidNameForFrame(const ::rtl::OUString& sName); +}; + +} // namespace framework + +#endif // #ifndef __FRAMEWORK_TARGETHELPER_HXX_ |