001// Copyright (c) FIRST and other WPILib contributors.
002// Open Source Software; you can modify and/or share it under the terms of
003// the WPILib BSD license file in the root directory of this project.
004
005package org.wpilib.networktables;
006
007/** NetworkTables publish/subscribe option. */
008public sealed interface PubSubOption {
009  /**
010   * How frequently changes will be sent over the network. NetworkTables may send more frequently
011   * than this (e.g. use a combined minimum period for all values) or apply a restricted range to
012   * this value. The default if unspecified is 100 ms.
013   *
014   * @param period time between updates, in seconds
015   */
016  record Periodic(double period) implements PubSubOption {}
017
018  /**
019   * If enabled, sends all value changes over the network. This option defaults to disabled.
020   *
021   * @param enabled True to enable, false to disable
022   */
023  record SendAll(boolean enabled) implements PubSubOption {}
024
025  /**
026   * If enabled on a subscription, does not request value changes. This option defaults to disabled.
027   *
028   * @param enabled True to enable, false to disable
029   */
030  record TopicsOnly(boolean enabled) implements PubSubOption {}
031
032  /**
033   * If enabled, preserves duplicate value changes (rather than ignoring them). This option defaults
034   * to disabled.
035   *
036   * @param enabled True to enable, false to disable
037   */
038  record KeepDuplicates(boolean enabled) implements PubSubOption {}
039
040  /**
041   * Polling storage for subscription. Specifies the maximum number of updates NetworkTables should
042   * store between calls to the subscriber's readQueue() function. Defaults to 1 if sendAll is
043   * false, 20 if sendAll is true.
044   *
045   * @param depth number of entries to save for polling.
046   */
047  record PollStorage(int depth) implements PubSubOption {}
048
049  /**
050   * For subscriptions, specify whether remote value updates should not be queued for readQueue().
051   * See also disableLocal(). Defaults to false (remote value updates are queued).
052   *
053   * @param disabled True to disable, false to enable
054   */
055  record DisableRemote(boolean disabled) implements PubSubOption {}
056
057  /**
058   * For subscriptions, specify whether local value updates should not be queued for readQueue().
059   * See also disableRemote(). Defaults to false (local value updates are queued).
060   *
061   * @param disabled True to disable, false to enable
062   */
063  record DisableLocal(boolean disabled) implements PubSubOption {}
064
065  /**
066   * Don't queue value updates for the given publisher. Only has an effect on subscriptions. Only
067   * one exclusion may be set.
068   *
069   * @param publisher publisher to exclude
070   */
071  record ExcludePublisher(Publisher publisher) implements PubSubOption {}
072
073  /**
074   * Don't queue value updates for the given publisher. Only has an effect on subscriptions. Only
075   * one exclusion may be set.
076   *
077   * @param publisher publisher handle to exclude
078   */
079  record ExcludePublisherHandle(int publisher) implements PubSubOption {}
080
081  /**
082   * Don't queue value updates for the internal publisher for an entry. Only has an effect on
083   * entries.
084   *
085   * @param enabled True to enable, false to disable
086   */
087  record ExcludeSelf(boolean enabled) implements PubSubOption {}
088
089  /**
090   * For subscriptions, don't share the existence of the subscription with the network. Note this
091   * means updates will not be received from the network unless another subscription overlaps with
092   * this one, and the subscription will not appear in metatopics.
093   *
094   * @param enabled True to enable, false to disable
095   */
096  record Hidden(boolean enabled) implements PubSubOption {}
097
098  /** Indicates only value changes will be sent over the network (default). */
099  PubSubOption SEND_CHANGES = new SendAll(false);
100
101  /** Indicates all value changes will be sent over the network. */
102  PubSubOption SEND_ALL = new SendAll(true);
103
104  /** Indicates both topics and values will be sent over the network (default). */
105  PubSubOption TOPICS_AND_VALUES = new TopicsOnly(false);
106
107  /** Indicates only topics will be sent over the network. */
108  PubSubOption TOPICS_ONLY = new TopicsOnly(true);
109
110  /** Indicates duplicate value changes will be ignored (default). */
111  PubSubOption IGNORE_DUPLICATES = new KeepDuplicates(false);
112
113  /** Indicates duplicate value changes will be preserved. */
114  PubSubOption KEEP_DUPLICATES = new KeepDuplicates(true);
115
116  /** For subscriptions, indicates remote value updates will be queued for readQueue() (default). */
117  PubSubOption ENABLE_REMOTE = new DisableRemote(false);
118
119  /** For subscriptions, indicates remote value updates will not be queued for readQueue() . */
120  PubSubOption DISABLE_REMOTE = new DisableRemote(true);
121
122  /** For subscriptions, indicates local value updates will be queued for readQueue() (default). */
123  PubSubOption ENABLE_LOCAL = new DisableLocal(false);
124
125  /** For subscriptions, indicates local value updates will not be queued for readQueue() . */
126  PubSubOption DISABLE_LOCAL = new DisableLocal(true);
127
128  /**
129   * For entries, indicates value updates from the internal publisher will be included (default).
130   */
131  PubSubOption INCLUDE_SELF = new ExcludeSelf(false);
132
133  /** For entries, indicates value updates from the internal publisher will be excluded. */
134  PubSubOption EXCLUDE_SELF = new ExcludeSelf(true);
135
136  /** For subscriptions, indicates the subscription is visible to the network (default). */
137  PubSubOption VISIBLE = new Hidden(false);
138
139  /** For subscriptions, indicates the subscription is hidden from the network. */
140  PubSubOption HIDDEN = new Hidden(true);
141
142  /**
143   * How frequently changes will be sent over the network. NetworkTables may send more frequently
144   * than this (e.g. use a combined minimum period for all values) or apply a restricted range to
145   * this value. The default if unspecified is 100 ms.
146   *
147   * @param period time between updates, in seconds
148   * @return option
149   */
150  static PubSubOption periodic(double period) {
151    return new Periodic(period);
152  }
153
154  /**
155   * Polling storage for subscription. Specifies the maximum number of updates NetworkTables should
156   * store between calls to the subscriber's readQueue() function. Defaults to 1 if sendAll is
157   * false, 20 if sendAll is true.
158   *
159   * @param depth number of entries to save for polling.
160   * @return option
161   */
162  static PubSubOption pollStorage(int depth) {
163    return new PollStorage(depth);
164  }
165
166  /**
167   * Don't queue value updates for the given publisher. Only has an effect on subscriptions. Only
168   * one exclusion may be set.
169   *
170   * @param publisher publisher handle to exclude
171   * @return option
172   */
173  static PubSubOption excludePublisher(int publisher) {
174    return new ExcludePublisherHandle(publisher);
175  }
176
177  /**
178   * Don't queue value updates for the given publisher. Only has an effect on subscriptions. Only
179   * one exclusion may be set.
180   *
181   * @param publisher publisher to exclude
182   * @return option
183   */
184  static PubSubOption excludePublisher(Publisher publisher) {
185    return new ExcludePublisher(publisher);
186  }
187}