1 /*============================================================================= 2 3 Library: CTK 4 5 Copyright (c) German Cancer Research Center, 6 Division of Medical and Biological Informatics 7 8 Licensed under the Apache License, Version 2.0 (the "License"); 9 you may not use this file except in compliance with the License. 10 You may obtain a copy of the License at 11 12 http://www.apache.org/licenses/LICENSE-2.0 13 14 Unless required by applicable law or agreed to in writing, software 15 distributed under the License is distributed on an "AS IS" BASIS, 16 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 17 See the License for the specific language governing permissions and 18 limitations under the License. 19 20 =============================================================================*/ 21 22 #ifndef CTKLOCATION_H 23 #define CTKLOCATION_H 24 25 #include <ctkPluginFrameworkExport.h> 26 27 #include <QObject> 28 29 class QUrl; 30 31 /** 32 * A ctkLocation represents a QUrl which may have a default value, may be read only, may 33 * or may not have a current value and may be cascaded on to a parent location. 34 */ 35 struct CTK_PLUGINFW_EXPORT ctkLocation 36 { 37 38 /** 39 * Constant which defines the filter string for acquiring the service which 40 * specifies the instance location. 41 */ 42 static const QString INSTANCE_FILTER; 43 44 /** 45 * Constant which defines the filter string for acquiring the service which 46 * specifies the install location. 47 */ 48 static const QString INSTALL_FILTER; 49 50 /** 51 * Constant which defines the filter string for acquiring the service which 52 * specifies the configuration location. 53 */ 54 static const QString CONFIGURATION_FILTER; 55 56 /** 57 * Constant which defines the filter string for acquiring the service which 58 * specifies the user location. 59 */ 60 static const QString USER_FILTER; 61 62 /** 63 * Constant which defines the filter string for acquiring the service which 64 * specifies the eclipse home location. 65 */ 66 static const QString CTK_HOME_FILTER; 67 68 ~ctkLocationctkLocation69 virtual ~ctkLocation() {} 70 71 /** 72 * Returns <code>true</code> if this location allows a default value to be assigned 73 * and <code>false</code> otherwise. 74 * 75 * @return whether or not this location can have a default value assigned 76 */ 77 virtual bool allowsDefault() const = 0; 78 79 /** 80 * Returns the default value of this location if any. If no default is available then 81 * <code>null</code> is returned. Note that even locations which allow defaults may still 82 * return <code>null</code>. 83 * 84 * @return the default value for this location or <code>null</code> 85 */ 86 virtual QUrl getDefault() const = 0; 87 88 /** 89 * Returns the parent of this location or <code>null</code> if none is available. 90 * 91 * @return the parent of this location or <code>null</code> 92 */ 93 virtual ctkLocation* getParentLocation() const = 0; 94 95 /** 96 * Returns the actual QUrl of this location. If the location's value has been set, 97 * that value is returned. If the value is not set and the location allows defaults, 98 * the value is set to the default and returned. In all other cases <code>null</code> 99 * is returned. 100 * 101 * @return the URL for this location or <code>null</code> if none 102 */ 103 virtual QUrl getUrl() const = 0; 104 105 /** 106 * Returns <code>true</code> if this location has a value and <code>false</code> 107 * otherwise. 108 * 109 * @return boolean value indicating whether or not the value is set 110 */ 111 virtual bool isSet() const = 0; 112 113 /** 114 * Returns <code>true</code> if this location represents a read only location and 115 * <code>false</code> otherwise. The read only character 116 * of a location is not in enforced in any way but rather expresses the intention of the 117 * location's creator. 118 * 119 * @return boolean value indicating whether the location is read only 120 */ 121 virtual bool isReadOnly() const = 0; 122 123 /** 124 * Sets and optionally locks the location's value to the given QUrl. If the location 125 * already has a value an exception is thrown. If locking is requested and fails, <code>false</code> 126 * is returned and the QUrl of this location is not set. 127 * 128 * @param value the value of this location 129 * @param lock whether or not to lock this location 130 * @return whether or not the location was successfully set and, if requested, locked. 131 * @throws ctkIllegalStateException if the location's value is already set 132 * @throws ctkRuntimeException if there was an unexpected problem while acquiring the lock 133 */ 134 virtual bool set(const QUrl& value, bool lock) = 0; 135 136 /** 137 * Sets and optionally locks the location's value to the given QUrl using the given lock file. If the location 138 * already has a value an exception is thrown. If locking is requested and fails, <code>false</code> 139 * is returned and the QUrl of this location is not set. 140 * 141 * @param value the value of this location 142 * @param lock whether or not to lock this location 143 * @param lockFilePath the path to the lock file. This path will be used to establish locks on this location. 144 * The path may be an absolute path or it may be relative to the given URL. If a <code>null</code> 145 * value is used then a default lock path will be used for this location. 146 * @return whether or not the location was successfully set and, if requested, locked. 147 * @throws ctkIllegalStateException if the location's value is already set 148 * @throws ctkRuntimeException if there was an unexpected problem while acquiring the lock 149 */ 150 virtual bool set(const QUrl& value, bool lock, const QString& lockFilePath) = 0; 151 152 /** 153 * Attempts to lock this location with a canonical locking mechanism and return 154 * <code>true</code> if the lock could be acquired. Not all locations can be 155 * locked. 156 * <p> 157 * Locking a location is advisory only. That is, it does not prevent other applications from 158 * modifying the same location 159 * </p> 160 * @return true if the lock could be acquired; otherwise false is returned 161 * 162 * @exception ctkRuntimeException if there was an unexpected problem while acquiring the lock 163 */ 164 virtual bool lock() = 0; 165 166 /** 167 * Releases the lock on this location. If the location is not already locked, no action 168 * is taken. 169 */ 170 virtual void release() = 0; 171 172 /** 173 * Returns <code>true</code> if this location is locked and <code>false</code> 174 * otherwise. 175 * @return boolean value indicating whether or not this location is locked 176 * @throws ctkRuntimeException if there was an unexpected problem reading the lock 177 */ 178 virtual bool isLocked() const = 0; 179 180 /** 181 * Constructs a new location. 182 * @param parent the parent location. A <code>null</code> value is allowed. 183 * @param defaultValue the default value of the location. A <code>null</code> value is allowed. 184 * @param readonly true if the location is read-only. 185 * @return a new location. 186 */ 187 virtual ctkLocation* createLocation(ctkLocation* parent, const QUrl& defaultValue, bool readonly) = 0; 188 189 /** 190 * Returns a URL to the specified path within this location. The path 191 * of the returned URL may not exist yet. It is the responsibility of the 192 * client to create the content of the data area returned if it does not exist. 193 * <p> 194 * This method can be used to obtain a private area within the given location. 195 * For example use the symbolic name of a plugin to obtain a data area specific 196 * to that plugin. 197 * </p> 198 * <p> 199 * Clients should check if the location is read only before writing anything 200 * to the returned data area. An <code>ctkRuntimeException</code> will be thrown if 201 * this method is called and the location URL has not been set and there is 202 * no default value for this location. 203 * </p> 204 * 205 * @param path the name of the path to get from this location 206 * @return the URL to the data area with the specified path. 207 * @throws ctkRuntimeException if the location URL is not already set 208 */ 209 virtual QUrl getDataArea(const QString& path) const = 0; 210 211 }; 212 213 Q_DECLARE_INTERFACE(ctkLocation, "org.commontk.service.datalocation.Location") 214 215 #endif // CTKLOCATION_H 216