bundles/org.simantics.db/src/org/simantics/db/ServiceLocator.java

   1 /*******************************************************************************\r
   2  * Copyright (c) 2007, 2010 Association for Decentralized Information Management\r
   3  * in Industry THTH ry.\r
   4  * All rights reserved. This program and the accompanying materials\r
   5  * are made available under the terms of the Eclipse Public License v1.0\r
   6  * which accompanies this distribution, and is available at\r
   7  * http://www.eclipse.org/legal/epl-v10.html\r
   8  *\r
   9  * Contributors:\r
  10  *     VTT Technical Research Centre of Finland - initial API and implementation\r
  11  *******************************************************************************/\r
  12 package org.simantics.db;\r
  13 \r
  14 import org.simantics.db.exception.ServiceNotFoundException;\r
  15 \r
  16 /**\r
  17  * <p>\r
  18  * A component with which one or more services are registered. The services can\r
  19  * be retrieved from this locator using the class representing the interface the\r
  20  * service must implement as a key. For example:\r
  21  * </p>\r
  22  * \r
  23  * <pre>\r
  24  * SomeService service = session.getService(SomeService.class);\r
  25  * </pre>\r
  26  * \r
  27  * <p>\r
  28  * If you want your service be disposed when the {@link ServiceLocator} is\r
  29  * disposed, make your service implement {@link Disposable}.\r
  30  * </p>\r
  31  * \r
  32  * <p>\r
  33  * Implementations must be thread-safe.\r
  34  * </p>\r
  35  * \r
  36  * <p>\r
  37  * This interface is not to be implemented or extended by clients.\r
  38  * </p>\r
  39  * \r
  40  * <strong>NOTE:</strong> this is a blatant copy of IServiceLocator in\r
  41  * org.eclipse.ui.services, but for the purposes of the DB connection interface.\r
  42  * \r
  43  * @see Disposable\r
  44  * \r
  45  * @author eclipse.org\r
  46  * @author Tuukka Lehtonen\r
  47  */\r
  48 public interface ServiceLocator {\r
  49 \r
  50     /**\r
  51      * Retrieves the service corresponding to the given API.\r
  52      * \r
  53      * @param api This is the interface that the service implements and was\r
  54      *        registered with using {@link #registerService(Class, Object)}.\r
  55      *        Must not be <code>null</code>.\r
  56      * @return the requested service\r
  57      * @throws ServiceNotFoundException if a requested service is not available\r
  58      */\r
  59     public <T> T getService(Class<T> api) throws ServiceNotFoundException;\r
  60 \r
  61     /**\r
  62      * Tries to retrieve the service corresponding to the given API.\r
  63      * \r
  64      * @param api\r
  65      *            This is the interface that the service implements. Must not be\r
  66      *            <code>null</code>.\r
  67      * @return The service, or <code>null</code> if no such service could be\r
  68      *         found.\r
  69      */\r
  70     public <T> T peekService(Class<T> api);\r
  71 \r
  72     /**\r
  73      * Whether this service exists within the scope of this service locator.\r
  74      * This does not include looking for the service within the scope of the\r
  75      * parents. This method can be used to determine whether a particular\r
  76      * service supports nesting in this scope.\r
  77      * \r
  78      * @param api\r
  79      *            This is the interface that the service implements. Must not be\r
  80      *            <code>null</code>.\r
  81      * @return <code>true</code> iff the service locator can find a service\r
  82      *         for the given API; <code>false</code> otherwise.\r
  83      */\r
  84     public boolean hasService(Class<?> api);\r
  85 \r
  86     /**\r
  87      * @param api the api that must be implemented by the specified service\r
  88      * @param service the service implementation\r
  89      */\r
  90     public <T> void registerService(Class<T> api, T service);\r
  91 \r
  92 }\r