View Javadoc

1   /* This file is part of COPAL (COntext Provisioning for All).
2    *
3    * COPAL is a part of SM4All (Smart hoMes for All) project.
4    *
5    * COPAL is free software: you can redistribute it and/or modify
6    * it under the terms of the GNU Lesser General Public License as published by
7    * the Free Software Foundation, either version 3 of the License, or
8    * (at your option) any later version.
9    *
10   * COPAL is distributed in the hope that it will be useful,
11   * but WITHOUT ANY WARRANTY; without even the implied warranty of
12   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13   * GNU Lesser General Public License for more details.
14   *
15   * You should have received a copy of the GNU Lesser General Public License
16   * along with COPAL. If not, see <http://www.gnu.org/licenses/>.
17   */
18  package at.ac.tuwien.infosys.sm4all.copal.api.service;
19  
20  import at.ac.tuwien.infosys.sm4all.copal.api.event.ContextEvent;
21  import at.ac.tuwien.infosys.sm4all.copal.api.event.ContextEventType;
22  import at.ac.tuwien.infosys.sm4all.copal.api.event.CurrentAction;
23  import at.ac.tuwien.infosys.sm4all.copal.api.listener.ContextListener;
24  import at.ac.tuwien.infosys.sm4all.copal.api.query.ActionQuery;
25  import at.ac.tuwien.infosys.sm4all.copal.api.query.ContextQuery;
26  import at.ac.tuwien.infosys.sm4all.copal.api.query.ProcessedEventQuery;
27  import at.ac.tuwien.infosys.sm4all.copal.api.query.QueryObserver;
28  import at.ac.tuwien.infosys.sm4all.copal.api.query.QueryState;
29  import at.ac.tuwien.infosys.sm4all.copal.api.util.Observable;
30  
31  /**
32   * Interface which COPAL core provides to create {@link ContextQuery}s which can
33   * be used to register and unregister {@link ContextListener}s.
34   * 
35   * @author sanjin
36   */
37  public interface ContextQueryFactory extends
38          Observable<QueryState, ContextQuery, QueryObserver> {
39  
40      /**
41       * Create instance of {@link ProcessedEventQuery} with specified globally
42       * unique name which catches all events with specified name of
43       * {@link ContextEventType}. If a query with same name was previously
44       * created the instance of {@link ContextQuery} created in first call will
45       * be returned, thus caller of this method has to ensure that specified
46       * event type in both calls is same.
47       * 
48       * @param name the globally unique name of the {@link ProcessedEventQuery}.
49       * @param listenedType the name of listened {@link ContextEventType}.
50       * @return the context query.
51       * @throws RedefinitionOfQueryException if query with same name and
52       *         different event type is already created.
53       * @see ProcessedEventQuery#ProcessedEventQuery(String, String)
54       */
55      ProcessedEventQuery create(String name, String listenedType)
56              throws RedefinitionOfQueryException;
57  
58      /**
59       * Create instance of {@link ProcessedEventQuery} with specified globally
60       * unique name which catches all events with specified name
61       * {@link ContextEventType} for which specified criteria evaluates to
62       * <code>true</code>. Criteria is a logical expression using event's
63       * properties to further separate the events of interest. If a query with
64       * same name was previously created the instance of {@link ContextQuery}
65       * created in first call will be returned, thus caller of this method has to
66       * ensure that specified event type and criteria in both calls are same.
67       * 
68       * @param name the globally unique name of the {@link ProcessedEventQuery}.
69       * @param listenedType the name of listened {@link ContextEventType}.
70       * @param criteria the logical expression.
71       * @return the context query.
72       * @throws RedefinitionOfQueryException if query with same name and
73       *         different event type or criteria is already created.
74       * @see ProcessedEventQuery#ProcessedEventQuery(String, String, String)
75       */
76      ProcessedEventQuery create(String name, String listenedType, String criteria)
77              throws RedefinitionOfQueryException;
78  
79      /**
80       * Create instance of {@link ActionQuery} for {@link ContextEvent}s that
81       * have name of their {@link ContextEventType} equal to specified listened
82       * type and have name of their {@link CurrentAction} equal to specified
83       * action name
84       * 
85       * @param listenedType the name of listened {@link ContextEventType}.
86       * @param actionName the name of handled {@link CurrentAction}.
87       * @return the action query.
88       * @see ActionQuery#ActionQuery(String, String)
89       */
90      ActionQuery createActionQuery(String listenedType, String actionName);
91  
92      /**
93       * Returns all currently non-destroyed {@link ContextQuery}s.
94       * 
95       * @return all currently non-destroyed {@link ContextQuery}s.
96       */
97      ContextQuery[] getQueries();
98  
99      /**
100      * @param name the name of a {@link ContextQuery}.
101      * @return the {@link ContextQuery} used in creation; or <code>null</code>
102      *         if there is no non-destroyed {@link ContextQuery} with specified
103      *         name.
104      */
105     ContextQuery getQuery(String name);
106 
107     /**
108      * @param eventType the name of the {@link ContextEventType}.
109      * @return all {@link ContextQuery}s which listen on events of
110      *         {@link ContextEventType} that has name equal to specified
111      *         <code>eventType</code>.
112      */
113     ContextQuery[] getQueries(String eventType);
114 }