The SIRI repeater application is a command-line application that provides a repeater/proxy between existing SIRI data sources and other SIRI clients. The repeater serves to provide:
The app is still under active development as we work to flesh out these features.
The general idea is that the repeater application connects to your existing SIRI data sources as a client and also provides a server to rebroadcast SIRI data to other clients.
In the this documentation, we'll often refer to PRIVATE SIRI sources, which are the SIRI data sources you wish to proxy, and PUBLIC SIRI clients, which will be proxied by the application.
You can download the latest application here:
Note that we also provide an RPM package of the application as well.
You'll need a Java 1.6 runtime installed to run the client. To run the client:
java -jar onebusaway-siri-repeater-cli.jar [-args] request [request ...]
Each request command line argument indicates a private SIRI data source to connect to. The request has the following syntax:
Key=Value,Key=Value,...
At minimum, you need to specify a Url that indicates the SIRI resource to connect to, and a ModuleType that indicates the SIRI module type to request. Additional keys specific to the module type can be used to further filter the request. For example:
Url=http://host:port/path,ModuleType=VEHICLE_MONITORING
For more details, see the full command-line request spec documentation.
There are two types of urls you might specify to the repeater application:
There may be situations, as determined by your network/firewall/NAT configuration, that require a different public url that external clients will try to connect to and a private url that the application will actually bind to (with your firewall connecting the dots).
For example, your public url for incoming client requests might be http://yourdomain.com/ while internally you want the SIRI repeater application to listen at http://localhost:8080, with port-forwarding linking the two. In such a case, you'd specify -clientUrl http://yourdomain.com/ and -privateClientUrl http://localhost:8080.
Filters provide functionality to modify and transform data as it passes through the repeater. Filters can be conditionally applied and chained to provide powerful data customization. There are two primary pieces to a filter: matching rules to determine when a filter is applied and the filter itself. We cover both pieces in the following sections.
Consider the scenario where we have an incoming SIRI Vehicle Monitoring data stream coming from an internal AVL system. We wish to share that data with external developers, but we first want to remove sensitive data from the stream, such as operator ids. We could specify the following filter:
-filter Match.ModuleType=VEHICLE_MONITORING,Match.RequestorRef=JoeUser,Filter.Type=Elements, Filter.Element.VehicleActivity.MonitoredVehicleJourney.OperatorRef
This filter specification can be described in terms of its specific arguments:
For complete details on matching and filter rules, see the following sections.
Matching rules determine when a filter is applied to a particular pub/sub data stream. Right now, we support a simple matching syntax that allows you to match the parameters of a subscription. You can specify any or all these m
Each matching rule includes a match_spec that determines how the target value will be matched. We support the following matchers:
We support some built-in filter functionality. If you are looking to implement your own filter functionality beyond what is possible out-of-the-box, see the next section. Right now, we support one simple element-based filtering modeling out-of-the-box. To use this filter, simply specify:
You can then specify multiple Filter.Element.XXX=YYY rules, where XXX is an XML element expression path and YYY is the filter value for any matching elements. Note that the path is specified RELATIVE to the module delivery sub-element, not the root SIRI/ element. For example, if you specified a Match.ModuleType=VEHICLE_MONITORING, your filter will be operating relative to a VehicleMonitoringDelivery/ elements. Thus, if we want to filter the OperatorRef/ out of the data stream, we'd specify:
Note that we will filter ALL matching sub-elements. That is, a particular ServiceDelivery/ might contain multiple VehicleMonitoringDelivery/ elements, which might contain multiple VehicleActivity/ elements. We'll filter all of these matching elements. In terms of the actually element value, we clear the value by default. You can optionally specify a NEW value using the following syntax:
If you need more complex filter behavior, you can additionally specify and implement your own filter. The repeater application is written in Java, which means you can easily implement your own filter and add it to the application.
The key interface to implement for a filter is org.onebusaway.siri.core.filters.SiriModuleDeliveryFilter. The interface looks like:
public interface SiriModuleDeliveryFilter {
public AbstractServiceDeliveryStructure filter(ServiceDelivery delivery, AbstractServiceDeliveryStructure moduleDelivery);
}Recall that a SIRI service delivery payload typically looks like:
<Siri>
<ServiceDelivery>
<StopMonitoringDelivery/>
<VehicleMonitoringDelivery/>
...
</ServiceDelivery>
</Siri>We have a parent <ServiceDelivery/> element wrapping module-specific delivery elements. The filter interface operates on these module-specific delivery elements. Specifically, the filter takes the parent <ServiceDelivery/> element and the module-specific delivery element as argument and returns a filtered module delivery element, or null if the element should be filtered out completely. Your filter implementation can simply return the input module delivery object, perhaps modified in some way. It can also return an entirely new module delivery object or null to indicate no result should be published to the client.
To create filter class of your own, you'll need to add the onebusaway-siri-repeater-cli.jar to your developer classpath so that Java can find the definition for SiriModuleDeliveryFilter.
To include your custom filter, use the Filter.Class parameter to specify the full class name of your filter.
-filter Filter.Class=package.FilterClassName,...
The class files for your custom filter will also need to be included in the Java classpath when running the application.
We also provide an RPM package of of the onebusaway-siri-repeater-cli SIRI repeater application. The package should make it easy to deploy the repeater as a service on a Linux server.
You can download the latest RPM here:
Note: For complicated reasons, we offer a ZIP file download containing the RPM. Extract the ZIP to get at the rpm inside.
Install the RPM like you would any other:
rpm -i onebusaway-siri-repeater-VERSION.noarch.rpm
Note that you typically need to be root to install an RPM.
The primary configuration file for the repeater is:
/etc/onebusaway-siri-repeater/onebusaway-siri-repeater.conf
The file will contain a couple of options by default. The one you are most concerned with is REPEATER_ARGS:
# Custom onebusaway-siri-repeater arguments go here REPEATER_ARGS="..."
REPEATER_ARGS accepts the same command-line arguments as the stand-alone onebusaway-siri-repeater-cli application. As a quick example, the following config sets the requestor ref to me and subscribes to vehicle monitoring messages from http://host:8080/subscribe.xml:
# Custom onebusaway-siri-repeater arguments go here REPEATER_ARGS="-id me Url=http://host:8080/subscribe.xml,ModuleType=VEHICLE_MONITORING"
You can use standard init.d scripts to start and stop the onebusaway-siri-repeater daemon:
/etc/init.d/onebusaway-siri-repeater {start|stop|restart|status}You can also use the built-in service command to start and stop the service as well:
service onebusaway-siri-repeater {start|stop|restart|status}You can also control how the service is started on boot using the chkconfig command.