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.service.copal;
19  
20  import at.ac.tuwien.infosys.sm4all.copal.api.ActionQuery;
21  import at.ac.tuwien.infosys.sm4all.copal.api.ContextListener;
22  import at.ac.tuwien.infosys.sm4all.copal.api.ContextQuery;
23  import at.ac.tuwien.infosys.sm4all.copal.api.ProcessedEventQuery;
24  import at.ac.tuwien.infosys.sm4all.copal.api.ProcessorAction;
25  import at.ac.tuwien.infosys.sm4all.copal.api.RedefinitionOfQueryException;
26  import at.ac.tuwien.infosys.sm4all.copal.api.event.ContextEventType;
27  
28  /**
29   * Interface which COPAL core provides to create {@link ContextQuery}s which can
30   * be used to register and unregister {@link ContextListener}s.
31   * 
32   * @author sanjin
33   */
34  public interface ContextQueryFactory {
35  
36      /**
37       * Create an instance of {@link ActionQuery} with specified
38       * {@link ProcessorAction}.
39       * 
40       * @param action the processor action for events which this query should
41       *        catch.
42       * @return the action query.
43       * @see ActionQuery#ActionQuery(ProcessorAction)
44       */
45      ActionQuery create(ProcessorAction action);
46  
47      /**
48       * Create an instance of {@link ProcessedEventQuery} with specified globally
49       * unique name which catches all events with specified name of
50       * {@link ContextEventType}. If a query with same name was previously
51       * created the instance of {@link ContextQuery} created in first call will
52       * be returned, thus caller of this method has to ensure that specified
53       * event type in both calls is same.
54       * 
55       * @param name the globally unique name of the {@link ProcessedEventQuery}.
56       * @param eventType the name of {@link ContextEventType}.
57       * @return the context query.
58       * @throws RedefinitionOfQueryException if query with same name and
59       *         different event type is already created.
60       * @see ProcessedEventQuery#ProcessedEventQuery(String, String)
61       */
62      ProcessedEventQuery create(String name, String eventType)
63              throws RedefinitionOfQueryException;
64  
65      /**
66       * Create an instance of {@link ProcessedEventQuery} with specified globally
67       * unique name which catches all events with specified name
68       * {@link ContextEventType} for which specified criteria evaluates to
69       * <code>true</code>. Criteria is a logical expression using event's
70       * properties to further separate the events of interest. If a query with
71       * same name was previously created the instance of {@link ContextQuery}
72       * created in first call will be returned, thus caller of this method has to
73       * ensure that specified event type and criteria in both calls are same.
74       * 
75       * @param name the globally unique name of the {@link ProcessedEventQuery}.
76       * @param eventType the name of {@link ContextEventType}.
77       * @param criteria the logical expression.
78       * @return the context query.
79       * @throws RedefinitionOfQueryException if query with same name and
80       *         different event type or criteria is already created.
81       * @see ProcessedEventQuery#ProcessedEventQuery(String, String, String)
82       */
83      ProcessedEventQuery create(String name, String eventType, String criteria)
84              throws RedefinitionOfQueryException;
85  
86      /**
87       * @return all currently non-destroyed {@link ContextQuery}s.
88       */
89      ContextQuery[] getQueries();
90  
91      /**
92       * @param name the name of a {@link ContextQuery}.
93       * @return the {@link ContextQuery} used in creation; or <code>null</code>
94       *         if there is no non-destroyed {@link ContextQuery} with specified
95       *         name.
96       */
97      ContextQuery getQuery(String name);
98  
99      /**
100      * @param eventType the name of the {@link ContextEventType}.
101      * @return all {@link ContextQuery}s which listen on events of
102      *         {@link ContextEventType} that has name equal to specified
103      *         <code>eventType</code>.
104      */
105     ContextQuery[] getQueries(String eventType);
106 }