1 /**
2 * Copyright (C) 2010-14 pvmanager developers. See COPYRIGHT.TXT
3 * All rights reserved. Use is subject to license terms. See LICENSE.TXT
4 */
5 package org.epics.pvmanager;
6
7 import java.util.Collections;
8 import java.util.Map;
9 import java.util.logging.Logger;
10
11 /**
12 * Manages the connection for each channel of a data source.
13 *
14 * @author carcassi
15 */
16 public abstract class ChannelHandler {
17
18 private static final Logger log = Logger.getLogger(ChannelHandler.class.getName());
19 private final String channelName;
20
21 /**
22 * Creates a new channel handler.
23 *
24 * @param channelName the name of the channel this handler will be responsible of
25 */
26 public ChannelHandler(String channelName) {
27 if (channelName == null) {
28 throw new NullPointerException("Channel name cannot be null");
29 }
30 this.channelName = channelName;
31 }
32
33 /**
34 * Returns extra information about the channel, typically
35 * useful for debugging.
36 *
37 * @return a property map
38 */
39 public Map<String, Object> getProperties() {
40 return Collections.emptyMap();
41 }
42
43 /**
44 * Returns the name of the channel.
45 *
46 * @return the channel name; can't be null
47 */
48 public String getChannelName() {
49 return channelName;
50 }
51
52 /**
53 * Returns how many readers or writers are open on
54 * this channel.
55 *
56 * @return the number of open readers and writers
57 */
58 public abstract int getUsageCounter();
59
60 /**
61 * Returns how many readers are open on this channel.
62 *
63 * @return the number of open readers
64 */
65 public abstract int getReadUsageCounter();
66
67 /**
68 * Returns how many writers are open on this channel.
69 *
70 * @return the number of open writers
71 */
72 public abstract int getWriteUsageCounter();
73
74 /**
75 * Used by the data source to add a read request on the channel managed
76 * by this handler.
77 *
78 * @param subscription the data required for a subscription
79 */
80 protected abstract void addReader(ChannelHandlerReadSubscription subscription);
81
82 /**
83 * Used by the data source to remove a read request.
84 *
85 * @param subscription the subscription to remove
86 */
87 protected abstract void removeReader(ChannelHandlerReadSubscription subscription);
88
89 /**
90 * Used by the data source to prepare the channel managed by this handler
91 * for write.
92 *
93 * @param subscription the data required for the subscription
94 */
95 protected abstract void addWriter(ChannelHandlerWriteSubscription subscription);
96
97 /**
98 * Used by the data source to conclude writes to the channel managed by this handler.
99 *
100 * @param subscription the subscription to remove
101 */
102 protected abstract void removeWrite(ChannelHandlerWriteSubscription subscription);
103
104 /**
105 * Implements a write operation. Writes the newValues to the channel
106 * and call the callback when done.
107 *
108 * @param newValue new value to be written
109 * @param callback called when done or on error
110 */
111 protected abstract void write(Object newValue, ChannelWriteCallback callback);
112
113 /**
114 * Returns true if it is connected.
115 *
116 * @return true if underlying channel is connected
117 */
118 public abstract boolean isConnected();
119 }