AgentChannelsFilter (LSST CCS Graphical User Interface 4.2.11 API)

All Superinterfaces:

Savable

All Known Subinterfaces:

PersistableAgentChannelsFilter

All Known Implementing Classes:

AbstractChannelsFilter, CCSHealthFilter, CellTableView, CellView, ConfigurationFilter, CoreStates, DemoFilter, FilterFixed, FilterMonitored, FilterOutOfRange, GenericFilter, GenericFilterPersistable, GroupView.Filter, KeyDataAllSubsystemsFilter, PageFilter, RegExFilter, RegExRenamingFilter, States, SubsystemSelectorFilter, Versions
```
public interface AgentChannelsFilter
extends Savable
```
A filter that selects a set of data channels and defines their presentation. Original channels are identified by their unique paths (slash-separated string, the first segment is the subsystem name). This filter maps each original channel to zero or more display paths in [group//]path1/.../pathN format. The display path determines how the channel is presented in the graphical console.
The exact interpretation of filter output depends on the tool using the filter. In general, a data channel is accepted by this filter if all of the following is true:
- getOriginChannels() method returns null, or the original channel satisfies one of the channel selectors returned by this method.
- getDisplayPaths(AgentChannel channel) method returns a non-empty list.
- getDisplayChannels() method returns null, or at least one of the display paths returned by getDisplayPaths(AgentChannel channel) is contained by the list returned by getDisplayChannels().
Some tools might not have access to AgentChannel instances. They will use
getDisplayPaths(String originalPath) and
static List<String> getDisplayPaths(AgentChannelsFilter filter, String originalPath)
methods instead.
List<String> getOriginChannels() may return channel selectors of several types (note that interpretation of some selectors depends on the list returned by getAgents() method):
- Complete path.
- Path template in the "[agent]/[partial path][/]" format. Templates that omit the agent name are expanded against all agents whose names are in the getAgents() list (or all agents present on the buses if that list is null). Templates that end with "/" match all channels that start with "agent/partial path/".
- Arbitrary regular expression (to be matched against the entire original path).
- Attribute selector strings in the "[agent.name=value&][agent.type=value&][agent.key[=value]&…&agent.key[=value]&][key[=value]&…&key[=value]]" format, where key and value are names and values of agent properties or static channel attributes. If value is omitted, the existence of the attribute is checked.
Implementing notes:
Only List<String> getDisplayPaths(AgentChannel channel) and List<String> getDisplayPaths(String originPath) methods are called by clients that support mapping a single original channel to several display paths. However, since most filters map to a single display path, convenience methods String getDisplayPath(AgentChannel channel) and String getDisplayPath(String originPath) are provided to be implemented by such filters. Default implementations are as follows:
- List<String> getDisplayPaths(AgentChannel channel) forwards to String getDisplayPath(AgentChannel channel).
- List<String> getDisplayPaths(String originPath) forwards to String getDisplayPath(String originPath).
- String getDisplayPath(AgentChannel channel) forwards to String getDisplayPath(String originPath).
- String getDisplayPath(String originPath) leaves the path unchanged.
If neither of these methods is overridden, this filter will leave the paths unchanged but getOriginChannels() can be overridden to reject unwanted channels.
This interface is somewhat overcomplicated, and some of the method names are unfortunate, for historical reasons: in the original version of the framework, one-to-many mapping was not supported, data dictionary (and, therefore, an ability to look channels up by path) was not available, etc. In later development, it was necessary to keep this interface backward-compatible with any existing filters.
Author:

onoprien

Field Summary

Fields
Modifier and Type Field and Description

static String CATEGORY
Category for general purpose Persistable filters.

Fields
Modifier and Type	Field and Description
`static String`	`CATEGORY` Category for general purpose `Persistable` filters.

Method Summary

All Methods Static Methods Instance Methods Default Methods Deprecated Methods
Modifier and Type	Method and Description
`default List<String>`	`getAgents()` Returns a list of agent names accepted by this filter.
`default List<String>`	`getDisplayChannels()` Returns a list of display paths produced by this filter.
`default String`	`getDisplayPath(AgentChannel channel)` Returns the display path corresponding to the specified original channel.
`static List<String>`	`getDisplayPath(AgentChannelsFilter filter, String originPath)` Deprecated.
`default String`	`getDisplayPath(String originPath)` Returns the display channel corresponding to the specified original path.
`default List<String>`	`getDisplayPaths(AgentChannel channel)` Returns a list of display channels for the specified original channel.
`default List<String>`	`getDisplayPaths(String originPath)` Returns a list of display channels for the specified original path.
`default List<String>`	`getFields(boolean compact)` Returns a list of attributes to display for each channel.
`default List<String>`	`getGroups()` Returns a list of groups of display paths produced by this filter.
`default String`	`getName()` Returns the name of this filter.
`default List<String>`	`getOriginChannels()` Returns a list of original channel selectors that might be accepted by this filter.
`default String`	`getOriginPath(String displayPath)` Returns the original path corresponding to the specified display channel.
`default List<String>`	`getOriginPaths(String displayPath)` Returns the list of original paths mapped to the specified display channel.
`static boolean`	`isSelector(String code)` Deprecated.
`static boolean`	`matchTemplate(String path, String template)` Deprecated.

Methods inherited from interface org.lsst.ccs.gconsole.services.persist.Savable
restore, save

- Field Detail
  - CATEGORY
```
static final String CATEGORY
```
    Category for general purpose Persistable filters.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getName
```
default String getName()
```
    Returns the name of this filter. The default implementation returns null.
    
    Returns:
    
    Name of this filter, or null if this filter has no name.
  - getAgents
```
default List<String> getAgents()
```
    Returns a list of agent names accepted by this filter. The list returned by this method affects interpretation of channel selectors returned by getOriginChannels(): every selector that does not explicitly specify agent is only applied to agents from the list.
    The default implementation returns null.
    
    Returns:
    
    Agent names accepted by this filter, or null if any agent is accepted.
  - getOriginChannels
```
default List<String> getOriginChannels()
```
    Returns a list of original channel selectors that might be accepted by this filter.
    The list returned by this method may contain channel selectors of several types (note that interpretation of some selectors depends on the list returned by getAgents() method):
    - Complete path.
    - Path template in the "[agent]/[partial path][/]" format. Templates that omit the agent name are expanded against all agents whose names are in the getAgents() list (or all agents present on the buses if that list is null). Templates that end with "/" match all channels that start with "agent/partial path/".
    - Arbitrary regular expression (to be matched against the entire original path).
    - Attribute selector strings in the "[agent.name=value&][agent.type=value&][agent.key[=value]&…&agent.key[=value]&][key[=value]&…&key[=value]]" format, where key and value are names and values of agent properties or static channel attributes. If value is omitted, the existence of the attribute is checked.
    The default implementation returns null.
    Returns:
    
    Original channel paths accepted by this filter, or null if any original path for which getDisplayPaths(org.lsst.ccs.gconsole.services.aggregator.AgentChannel) returns a non-empty list is accepted.
  - getDisplayChannels
```
default List<String> getDisplayChannels()
```
    Returns a list of display paths produced by this filter. Typically, if this method returns a non-null list, components downstream from this filter will display this fixed set of channels, whether or not the data is actually available. If this method returns null, all display paths produced by getDisplayPaths(AgentChannel channel) for original channels accepted by getOriginChannels() should be displayed.
    The default implementation returns null.
    
    Returns:
    
    Display paths produced by this filter, or null if the set of display paths is not constrained by this filter.
  - getFields
```
default List<String> getFields(boolean compact)
```
    Returns a list of attributes to display for each channel. The default implementation returns null.
    
    Parameters:
    
    compact - If true, returns a list of columns in a compact view.
    
    Returns:
    
    Display fields, or null if this filter does not provides any hints on what attributes should be displayed.
  - getGroups
```
default List<String> getGroups()
```
    Returns a list of groups of display paths produced by this filter. The default implementation returns null.
    
    Returns:
    
    Display groups, or null if the set of groups is not constrained by this filter.
  - getDisplayPaths
```
default List<String> getDisplayPaths(AgentChannel channel)
```
    Returns a list of display channels for the specified original channel. This method is called by clients that have access to original AgentChannel instances (like monitoring views).
    Not that if the specified original channel is not accepted by this filter, this method should return an empty list. null should never be returned.
    The default implementation returns a singleton list that contains a string returned by getDisplayPath(AgentChannel) method.
    
    Parameters:
    
    channel - Original data channel.
    
    Returns:
    
    List of display channels.
  - getDisplayPaths
```
default List<String> getDisplayPaths(String originPath)
```
    Returns a list of display channels for the specified original path. This method is called by clients that do not have access to original AgentChannel instances (like the trending tool).
    If the specified original channel is not accepted by this filter, this method should return an empty list. null should never be returned.
    The default implementation returns a singleton list that contains a string returned by getDisplayPath(String) method.
    
    Parameters:
    
    originPath - Original path.
    
    Returns:
    
    List of display channels.
  - getDisplayPath
```
default String getDisplayPath(AgentChannel channel)
```
    Returns the display path corresponding to the specified original channel. This method is used directly by clients that expect each original channel to be mapped to no more than one display path. It can also be overridden to define a path returned in a singleton list by If the original channel is mapped to multiple display paths, this method may return one of them, or null if the clients that rely on mapping to a single display path should ignore the specified channel.
    The default implementation forwards the call to getDisplayPath(String) method. Subclasses may override it to take into account channel attributes and metadata.
    
    Parameters:
    
    channel - Original data channel.
    
    Returns:
    
    Display path, or null if the provided channel is not accepted by this filter.
  - getDisplayPath
```
default String getDisplayPath(String originPath)
```
    Returns the display channel corresponding to the specified original path. If the original channel is mapped to multiple display paths, this method may return one of them, or null.
    If the specified original channel is not accepted by this filter, this method should return an empty list. null should never be returned.
    The default implementation returns an unmodified original path.
    
    Parameters:
    
    originPath - Original path.
    
    Returns:
    
    List of display channels.
  - getOriginPaths
```
default List<String> getOriginPaths(String displayPath)
```
    Returns the list of original paths mapped to the specified display channel.
    The default implementation returns a list that contains one element - the path returned by getOriginPath(...) - or an empty list if getOriginPath(...) returns null.
    
    Parameters:
    
    displayPath - Display channel path.
    
    Returns:
    
    Original paths, or an empty list if the specified path does not correspond to any original channel.
  - getOriginPath
```
default String getOriginPath(String displayPath)
```
    Returns the original path corresponding to the specified display channel. If multiple original paths are mapped to the specified display path, this method may return one of them, or null.
    The default implementation returns the display path provided as an argument.
    
    Parameters:
    
    displayPath - Display channel path.
    
    Returns:
    
    Original path, or null if the specified path does not correspond to any original channel.
  - getDisplayPath
```
@Deprecated
static List<String> getDisplayPath(AgentChannelsFilter filter,
                                               String originPath)
```
    Deprecated.
    
    Returns a list of display paths for the specified original path, applying the provided filter. This method takes into account the output of getDisplayPaths(originPath), getDisplayChannels(), getAgents(), and getOriginChannels(). Templates in the list of origin paths returned by the filter are honored but attribute selectors are ignored.
    
    Parameters:
    
    filter - Filter to apply.
    
    originPath - Origin path.
    
    Returns:
    
    List of display path.
  - matchTemplate
```
@Deprecated
static boolean matchTemplate(String path,
                                         String template)
```
    Deprecated.
    
    Checks whether the path matches the template.
    
    Parameters:
    
    path - Origin path.
    
    template - Path template.
    
    Returns:
    
    True if the path matches.
  - isSelector
```
@Deprecated
static boolean isSelector(String code)
```
    Deprecated.
    
    Checks whether the specified string is in the channel selector format (as opposed to explicit path or template).
    
    Parameters:
    
    code - String to test.
    
    Returns:
    
    true if the specified string is a channel selector.

Interface AgentChannelsFilter

Implementing notes:

Field Summary

Method Summary

Methods inherited from interface org.lsst.ccs.gconsole.services.persist.Savable

Field Detail

CATEGORY

Method Detail

getName

getAgents

getOriginChannels

getDisplayChannels

getFields

getGroups

getDisplayPaths

getDisplayPaths

getDisplayPath

getDisplayPath

getOriginPaths

getOriginPath

getDisplayPath

matchTemplate

isSelector