View Javadoc

1   /*
2    * Copyright (C) 2007 ETH Zurich
3    *
4    * This file is part of Fosstrak (www.fosstrak.org).
5    *
6    * Fosstrak is free software; you can redistribute it and/or
7    * modify it under the terms of the GNU Lesser General Public
8    * License version 2.1, as published by the Free Software Foundation.
9    *
10   * Fosstrak 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 GNU
13   * Lesser General Public License for more details.
14   *
15   * You should have received a copy of the GNU Lesser General Public
16   * License along with Fosstrak; if not, write to the Free
17   * Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18   * Boston, MA  02110-1301  USA
19   */
20  
21  package org.fosstrak.epcis.repository;
22  
23  import org.fosstrak.epcis.model.ImplementationException;
24  import org.fosstrak.epcis.model.QueryResults;
25  import org.fosstrak.epcis.model.QueryTooLargeException;
26  
27  /**
28   * <p>
29   * The EPCIS Query Callback Interface is the path by which an EPCIS service
30   * delivers standing query results to a client.
31   * <p>
32   * Each time the EPCIS service executes a standing query according to a
33   * <code>QuerySchedule</code>, it SHALL attempt to deliver results to the
34   * subscriber by invoking one of the three methods of the Query Callback
35   * Interface. If the query executed normally, the EPCIS service SHALL invoke the
36   * {@link callbackResults(QueryResults) callbackResults} method. If the query
37   * resulted in a <code>QueryTooLargeException</code> or
38   * <code>ImplementationException</code>, the EPCIS service SHALL invoke the
39   * corresponding method of the Query Callback Interface.
40   * <p>
41   * Note that "exceptions" in the Query Callback Interface are not exceptions in
42   * the usual sense of an API exception, because they are not raised as a
43   * consequence of a client invoking a method. Instead, the exception is
44   * delivered to the recipient in a similar manner to a normal result, as an
45   * argument to an interface method.
46   */
47  public interface EpcisQueryCallbackInterface {
48  
49      /**
50       * Delivers the results of a standing query to the subscriber when the query
51       * executed normally.
52       * 
53       * @param resultData
54       *            The results of the execution of a standing query.
55       */
56      public void callbackResults(QueryResults resultData);
57  
58      /**
59       * Delivers the results of a standing query to the subscriber when the query
60       * resulted in a <code>QueryTooLargeException</code>.
61       * 
62       * @param e
63       *            The <code>QueryTooLargeException</code> thrown during
64       *            execution of a standing query.
65       */
66      public void callbackQueryTooLargeException(QueryTooLargeException e);
67  
68      /**
69       * Delivers the results of a standing query to the subscriber when the query
70       * resulted in a <code>ImplementationException</code>.
71       * 
72       * @param e
73       *            The <code>ImplementationException</code> thrown during
74       *            execution of a standing query.
75       */
76      public void callbackImplementationException(ImplementationException e);
77  }