hunt.database.driver.postgresql.pubsub.PostgreSQLSubscriber source code

1 /*
2  * Copyright (C) 2019, HuntLabs
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  *
16  */
17 module hunt.database.driver.postgresql.pubsub.PostgreSQLSubscriber;
18 
19 import hunt.database.driver.postgresql.PostgreSQLConnectOptions;
20 import hunt.database.driver.postgresql.PostgreSQLConnection;
21 import hunt.database.driver.postgresql.impl.pubsub.PostgreSQLSubscriberImpl;
22 
23 import hunt.database.base.AsyncResult;
24 
25 // import java.util.function.Function;
26 
27 /**
28  * A class for managing subscriptions using {@code LISTEN/UNLISTEN} to Postgres channels.
29  * <p/>
30  * The subscriber manages a single connection to Postgres.
31  */
32 // interface PgSubscriber {
33 
34 //     /**
35 //      * Create a subscriber.
36 //      *
37 //      * @param vertx the vertx instance
38 //      * @param options the connect options
39 //      * @return the subscriber
40 //      */
41 //     // static PgSubscriber subscriber(Vertx vertx, PgConnectOptions options) {
42 //     //     return new PgSubscriberImpl(vertx, options);
43 //     // }
44 
45 //     /**
46 //      * Return a channel for the given {@code name}.
47 //      *
48 //      * @param name the channel name
49 //      * <p/>
50 //      * This will be the name of the channel exactly as held by Postgres for sending
51 //      * notifications.  Internally this name will be truncated to the Postgres identifier
52 //      * maxiumum length of {@code (NAMEDATALEN = 64) - 1 == 63} characters, and prepared
53 //      * as a quoted identifier without unicode escape sequence support for use in
54 //      * {@code LISTEN/UNLISTEN} commands.  Examples of channel names and corresponding
55 //      * {@code NOTIFY} commands:
56 //      * <ul>
57 //      *   <li>when {@code name == "the_channel"}: {@code NOTIFY the_channel, 'msg'},
58 //      *   {@code NOTIFY The_Channel, 'msg'}, or {@code NOTIFY "the_channel", 'msg'}
59 //      *   succeed in delivering a message to the created channel
60 //      *   </li>
61 //      *   <li>when {@code name == "The_Channel"}: {@code NOTIFY "The_Channel", 'msg'},
62 //      *   succeeds in delivering a message to the created channel
63 //      *   </li>
64 //      *   <li></li>
65 //      * </ul>
66 //      * @return the channel
67 //      */
68 //     PgChannel channel(string name);
69 
70 //     /**
71 //      * Connect the subscriber to Postgres.
72 //      *
73 //      * @param handler the handler notified of the connection success or failure
74 //      * @return a reference to this, so the API can be used fluently
75 //      */
76 //     PgSubscriber connect(VoidHandler handler);
77 
78 //     /**
79 //      * Set the reconnect policy that is executed when the subscriber is disconnected.
80 //      * <p/>
81 //      * When the subscriber is disconnected, the {@code policy} function is called with the actual
82 //      * number of retries and returns an {@code amountOfTime} value:
83 //      * <ul>
84 //      *   <li>when {@code amountOfTime < 0}: the subscriber is closed and there is no retry</li>
85 //      *   <li>when {@code amountOfTime == 0}: the subscriber retries to connect immediately</li>
86 //      *   <li>when {@code amountOfTime > 0}: the subscriber retries after {@code amountOfTime} milliseconds</li>
87 //      * </ul>
88 //      * <p/>
89 //      * The default policy does not perform any retries.
90 //      *
91 //      * @param policy the policy to set
92 //      * @return a reference to this, so the API can be used fluently
93 //      */
94 //     PgSubscriber reconnectPolicy(Function!(Integer, Long) policy);
95 
96 //     /**
97 //      * Set an handler called when the subscriber is closed.
98 //      *
99 //      * @param handler the handler
100 //      * @return a reference to this, so the API can be used fluently
101 //      */
102 //     PgSubscriber closeHandler(VoidHandler handler);
103 
104 //     /**
105 //      * @return the actual connection to Postgres, it might be {@code null}
106 //      */
107 //     PgConnection actualConnection();
108 
109 //     /**
110 //      * @return whether the subscriber is closed
111 //      */
112 //     boolean closed();
113 
114 //     /**
115 //      * Close the subscriber, the retry policy will not be invoked.
116 //      */
117 //     void close();
118 
119 // }