rcap 1.3.1 → 2.0.0
Sign up to get free protection for your applications and to get access to all the features.
- data/CHANGELOG.md +5 -0
- data/README.md +78 -151
- data/Rakefile +1 -1
- data/lib/rcap/alert.rb +2 -2
- data/lib/rcap/base/alert.rb +446 -0
- data/lib/rcap/base/area.rb +228 -0
- data/lib/rcap/base/circle.rb +121 -0
- data/lib/rcap/base/event_code.rb +6 -0
- data/lib/rcap/base/geocode.rb +6 -0
- data/lib/rcap/base/info.rb +498 -0
- data/lib/rcap/base/parameter.rb +88 -0
- data/lib/rcap/base/point.rb +87 -0
- data/lib/rcap/base/polygon.rb +120 -0
- data/lib/rcap/base/resource.rb +168 -0
- data/lib/rcap/cap_1_0/alert.rb +59 -342
- data/lib/rcap/cap_1_0/area.rb +13 -188
- data/lib/rcap/cap_1_0/circle.rb +2 -100
- data/lib/rcap/cap_1_0/event_code.rb +8 -3
- data/lib/rcap/cap_1_0/geocode.rb +8 -3
- data/lib/rcap/cap_1_0/info.rb +16 -468
- data/lib/rcap/cap_1_0/parameter.rb +9 -67
- data/lib/rcap/cap_1_0/point.rb +2 -61
- data/lib/rcap/cap_1_0/polygon.rb +5 -95
- data/lib/rcap/cap_1_0/resource.rb +4 -144
- data/lib/rcap/cap_1_1/alert.rb +7 -412
- data/lib/rcap/cap_1_1/area.rb +13 -188
- data/lib/rcap/cap_1_1/circle.rb +2 -100
- data/lib/rcap/cap_1_1/event_code.rb +8 -3
- data/lib/rcap/cap_1_1/geocode.rb +7 -3
- data/lib/rcap/cap_1_1/info.rb +127 -386
- data/lib/rcap/cap_1_1/parameter.rb +4 -76
- data/lib/rcap/cap_1_1/point.rb +2 -61
- data/lib/rcap/cap_1_1/polygon.rb +5 -95
- data/lib/rcap/cap_1_1/resource.rb +37 -143
- data/lib/rcap/cap_1_2/alert.rb +8 -413
- data/lib/rcap/cap_1_2/area.rb +13 -188
- data/lib/rcap/cap_1_2/circle.rb +2 -100
- data/lib/rcap/cap_1_2/event_code.rb +8 -3
- data/lib/rcap/cap_1_2/geocode.rb +8 -3
- data/lib/rcap/cap_1_2/info.rb +132 -419
- data/lib/rcap/cap_1_2/parameter.rb +4 -76
- data/lib/rcap/cap_1_2/point.rb +2 -61
- data/lib/rcap/cap_1_2/polygon.rb +5 -92
- data/lib/rcap/cap_1_2/resource.rb +31 -134
- data/lib/rcap/config.rb +3 -0
- data/lib/{extensions → rcap/extensions}/array.rb +1 -1
- data/lib/rcap/extensions/date.rb +11 -0
- data/lib/{extensions → rcap/extensions}/date_time.rb +2 -5
- data/lib/{extensions → rcap/extensions}/string.rb +1 -1
- data/lib/{extensions → rcap/extensions}/time.rb +2 -4
- data/lib/rcap/utilities.rb +11 -11
- data/lib/rcap/validations.rb +7 -2
- data/lib/rcap/version.rb +1 -1
- data/lib/rcap.rb +21 -4
- data/spec/alert_spec.rb +69 -37
- data/spec/cap_1_0/alert_spec.rb +46 -61
- data/spec/cap_1_0/area_spec.rb +77 -37
- data/spec/cap_1_0/circle_spec.rb +26 -6
- data/spec/cap_1_0/event_code_spec.rb +10 -3
- data/spec/cap_1_0/geocode_spec.rb +11 -4
- data/spec/cap_1_0/info_spec.rb +74 -77
- data/spec/cap_1_0/parameter_spec.rb +18 -5
- data/spec/cap_1_0/point_spec.rb +9 -2
- data/spec/cap_1_0/polygon_spec.rb +52 -9
- data/spec/cap_1_0/resource_spec.rb +28 -21
- data/spec/cap_1_1/alert_spec.rb +47 -60
- data/spec/cap_1_1/area_spec.rb +66 -43
- data/spec/cap_1_1/circle_spec.rb +29 -6
- data/spec/cap_1_1/event_code_spec.rb +11 -3
- data/spec/cap_1_1/geocode_spec.rb +11 -3
- data/spec/cap_1_1/info_spec.rb +262 -118
- data/spec/cap_1_1/parameter_spec.rb +12 -3
- data/spec/cap_1_1/point_spec.rb +8 -2
- data/spec/cap_1_1/polygon_spec.rb +57 -18
- data/spec/cap_1_1/resource_spec.rb +70 -20
- data/spec/cap_1_2/alert_spec.rb +97 -110
- data/spec/cap_1_2/area_spec.rb +59 -41
- data/spec/cap_1_2/circle_spec.rb +15 -8
- data/spec/cap_1_2/event_code_spec.rb +11 -3
- data/spec/cap_1_2/geocode_spec.rb +11 -3
- data/spec/cap_1_2/info_spec.rb +266 -119
- data/spec/cap_1_2/parameter_spec.rb +11 -3
- data/spec/cap_1_2/point_spec.rb +10 -3
- data/spec/cap_1_2/polygon_spec.rb +25 -10
- data/spec/cap_1_2/resource_spec.rb +33 -28
- data/spec/{utilities_spec.rb → extensions_spec.rb} +0 -0
- data/spec/validations_spec.rb +18 -2
- metadata +20 -46
data/CHANGELOG.md
CHANGED
@@ -1,6 +1,11 @@
|
|
1
1
|
Change Log
|
2
2
|
==========
|
3
3
|
|
4
|
+
## 2.0.0 - 17 November 2012
|
5
|
+
|
6
|
+
* Changed initialisation to block/builder style
|
7
|
+
* Refactored RCAP so protocol versions are subclassed from classes in RCAP::Base module
|
8
|
+
|
4
9
|
## 1.3.1 - 25 February 2012
|
5
10
|
|
6
11
|
* Moved XML_PRETTY_PRINTER into RCAP namespace to avoid namespace issues
|
data/README.md
CHANGED
@@ -8,11 +8,6 @@ The Common Alerting Protocol is a lightweight standard to facilitate the distrib
|
|
8
8
|
|
9
9
|
RCAP currently supports CAP 1.0, 1.1 and 1.2.
|
10
10
|
|
11
|
-
Version
|
12
|
-
-------
|
13
|
-
|
14
|
-
1.3.0
|
15
|
-
|
16
11
|
Dependencies
|
17
12
|
------------
|
18
13
|
|
@@ -33,13 +28,6 @@ RCAP is distributed as a Ruby gem and is available from [Rubygems.org](http://ru
|
|
33
28
|
|
34
29
|
The gem is also available for download and manual installation at [www.aimred.com/gems](http://www.aimred.com/gems).
|
35
30
|
|
36
|
-
Web resources
|
37
|
-
-------------
|
38
|
-
|
39
|
-
* The RCAP project page can be found at [http://www.aimred.com/projects/rcap](http://www.aimred.com/projects/rcap)
|
40
|
-
* The RCAP API docs can be found at [http://www.aimred.com/projects/rcap/api](http://www.aimred.com/projects/rcap/api)
|
41
|
-
* A public git repository can be found at [git://github.com/farrel/RCAP.git](git://github.com/farrel/RCAP.git)
|
42
|
-
|
43
31
|
Usage
|
44
32
|
-----
|
45
33
|
|
@@ -47,93 +35,52 @@ To include RCAP into your application add the following require
|
|
47
35
|
|
48
36
|
require 'rcap'
|
49
37
|
|
50
|
-
All RCAP classes reside in the RCAP namespace but including the RCAP module makes the classes available at the top level without the RCAP prefix.
|
51
|
-
|
52
|
-
include RCAP:CAP_1_2 # Include RCAP:CAP_1_2 module into namespace
|
53
|
-
alert = Alert.new
|
54
|
-
|
55
38
|
### Creating an Alert
|
56
39
|
|
57
|
-
|
58
|
-
|
59
|
-
|
60
|
-
|
61
|
-
|
62
|
-
|
63
|
-
|
64
|
-
|
65
|
-
|
66
|
-
|
67
|
-
|
68
|
-
|
69
|
-
|
70
|
-
|
71
|
-
|
72
|
-
|
73
|
-
|
74
|
-
|
40
|
+
RCAP uses a 'builder' style syntax to create alerts.
|
41
|
+
|
42
|
+
alert = RCAP::CAP_1_2::Alert.new do |alert|
|
43
|
+
alert.sender = 'cape_town_disaster_relief@capetown.municipal.za'
|
44
|
+
alert.status = Alert::STATUS_ACTUAL
|
45
|
+
alert.msg_type = Alert::MSG_TYPE_ALERT
|
46
|
+
alert.scope = Alert::SCOPE_PUBLIC
|
47
|
+
|
48
|
+
alert.add_info do |info|
|
49
|
+
info.event = 'Liquid Petroleoum Tanker Fire'
|
50
|
+
info.language = 'en-ZA'
|
51
|
+
info.categories << Info::CATEGORY_TRANSPORT
|
52
|
+
info.categories << Info::CATEGORY_FIRE
|
53
|
+
info.urgency = Info::URGENCY_IMMEDIATE
|
54
|
+
info.severity = Info::SEVERITY_SEVERE
|
55
|
+
info.certainty = Info::CERTAINTY_OBSERVED
|
56
|
+
info.headline = 'LIQUID PETROLEOUM TANKER FIRE ON N2 INCOMING FREEWAY'
|
57
|
+
info.description = 'A liquid petroleoum tanker has caught fire on the N2 incoming freeway 1km
|
58
|
+
after the R300 interchange. Municipal fire fighting crews have been dispatched.
|
59
|
+
Traffic control officers are on the scene and have diverted traffic onto
|
60
|
+
alternate routes.'
|
61
|
+
|
62
|
+
info.add_area do |area|
|
63
|
+
area.area_desc = 'N2 Highway/R300 Interchange'
|
64
|
+
area.add_geocode do |geocode|
|
65
|
+
geocode.name = 'Intersection'
|
66
|
+
geocode.value = 'N2-15'
|
67
|
+
end
|
68
|
+
end
|
69
|
+
end
|
70
|
+
end
|
75
71
|
|
76
72
|
# Accessing attributes
|
77
|
-
alert.status
|
78
|
-
alert.infos
|
79
|
-
|
80
|
-
|
81
|
-
|
82
|
-
### Parsing an Alert From An External Source
|
83
|
-
|
84
|
-
RCAP can parse a CAP alert from a varierty of file formats. Besides the [standard XML](http://www.oasis-emergency.org/cap) representation, [YAML](http://yaml.org) and [JSON](http://json.org) support is also included.
|
85
|
-
|
86
|
-
To ensure the correct RCAP Alert object (RCAP::CAP_1_1::Alert or RCAP::CAP_1_2::Alert) is returned from an external source, a number of factories are defined in the RCAP::Alert module. If the version of the document to be parsed can not be ascertained a CAP 1.2 document will be assumed.
|
87
|
-
|
88
|
-
#### From XML
|
89
|
-
|
90
|
-
RCAP allows for the parsing of a CAP XML string
|
91
|
-
|
92
|
-
alert = RCAP::Alert.from_xml( xml_string )
|
93
|
-
|
94
|
-
#### From YAML
|
95
|
-
|
96
|
-
Alert messgaes can be read in from text files containing data formatted in [YAML](http://yaml.org) as generated by Alert#to_yaml.
|
97
|
-
|
98
|
-
alert = RCAP::Alert.from_yaml( yaml_string )
|
99
|
-
|
100
|
-
#### From JSON
|
101
|
-
|
102
|
-
An Alert can also be initialised from a [JSON](http://json.org) string produced by Alert#to_json
|
103
|
-
|
104
|
-
alert = RCAP::Alert.from_json( json_string )
|
105
|
-
|
106
|
-
### Validating an alert
|
107
|
-
|
108
|
-
The RCAP API aims to codify as many of the rules of the CAP XML format into validation rules that can be checked using the Assistance API. The following Info object has two attributes ('severity' and 'certainty') set to incorrect values.
|
109
|
-
|
110
|
-
info = Info.new( event: 'Liquid Petroleoum Tanker Fire',
|
111
|
-
language: 'en-ZA',
|
112
|
-
categories: [ Info::CATEGORY_TRANSPORT, Info::CATEGORY_FIRE ],
|
113
|
-
urgency: Info::URGENCY_IMMEDIATE,
|
114
|
-
severity: nil, # Severity is not assigned
|
115
|
-
certainty: 'Incorrect Certainty' ) # Certainty is assigned an incorrect value
|
116
|
-
|
117
|
-
puts "Is info valid: #{ info.valid? }"
|
118
|
-
info.errors.full_messages.each{ |message| puts "Error: #{ message }" }
|
119
|
-
|
120
|
-
Will produce the following output:
|
121
|
-
|
122
|
-
Is info valid: false
|
123
|
-
Error: severity is not present
|
124
|
-
Error: certainty can only be assigned the following values: Observed, Likely, Possible, Unlikely, Unknown
|
125
|
-
|
126
|
-
All RCAP classes include the Validation module.
|
127
|
-
|
128
|
-
A full spec suite using [RSpec](http://www.rspec.info) was used to test the validations and currently numbers over 1000 tests.
|
73
|
+
puts alert.status # "Actual"
|
74
|
+
info = alert.infos.first
|
75
|
+
puts info.language # "en-ZA"
|
76
|
+
puts info.categories.join( ', ' ) # "Transport, Fire"
|
77
|
+
puts info.areas.first # "N2 Highway/R300 Interchange"
|
129
78
|
|
130
79
|
### Exporting an Alert
|
131
80
|
|
132
|
-
|
81
|
+
Using the alert message created earlier
|
133
82
|
|
134
|
-
|
135
|
-
|
136
|
-
puts alert.to_xml # Print out CAP XML message
|
83
|
+
puts alert.to_xml
|
137
84
|
|
138
85
|
Will print the following CAP XML
|
139
86
|
|
@@ -163,69 +110,49 @@ Will print the following CAP XML
|
|
163
110
|
</info>
|
164
111
|
</alert>
|
165
112
|
|
166
|
-
|
167
|
-
|
168
|
-
|
169
|
-
|
170
|
-
|
171
|
-
|
172
|
-
|
173
|
-
|
174
|
-
|
175
|
-
|
176
|
-
|
177
|
-
|
178
|
-
|
179
|
-
|
180
|
-
|
181
|
-
|
182
|
-
|
183
|
-
|
184
|
-
|
185
|
-
|
186
|
-
|
187
|
-
|
188
|
-
Certainty: Observed
|
189
|
-
Headline: LIQUID PETROLEOUM TANKER FIRE ON N2 INCOMING FREEWAY
|
190
|
-
Description: |-
|
191
|
-
A liquid petroleoum tanker has caught fire on the N2 incoming freeway 1km
|
192
|
-
after the R300 interchange. Municipal fire fighting crews have been dispatched.
|
193
|
-
Traffic control officers are on the scene and have diverted traffic onto
|
194
|
-
alternate routes.
|
195
|
-
|
196
|
-
Note: If you use Ruby 1.8 the order of the attributes is jumbled due to hashes being unorderd (Ruby 1.9 implements ordered hashes). This does not affect the ability to parse documents generated from RCAP::Alert#to_yaml, it just makes things the output slightly messy.
|
197
|
-
|
198
|
-
#### To JSON
|
199
|
-
|
200
|
-
JSON is a text serialization format that can be easily loaded in a JavaScript environment.
|
201
|
-
|
202
|
-
alert.to_json
|
203
|
-
|
204
|
-
will produce the following JSON string
|
205
|
-
|
206
|
-
{"cap_version":"1.2",
|
207
|
-
"identifier":"0eb97e40-195b-437b-9a01-55fe89691def",
|
208
|
-
"sender":"cape_town_disaster_relief@capetown.municipal.za",
|
209
|
-
"sent":"2011-03-04T15:58:01+02:00",
|
210
|
-
"status":"Actual",
|
211
|
-
"msg_type":"Alert",
|
212
|
-
"scope":"Public",
|
213
|
-
"infos":[
|
214
|
-
{"language":"en-ZA",
|
215
|
-
"categories":["Transport","Fire"],
|
216
|
-
"event":"Liquid Petroleoum Tanker Fire",
|
217
|
-
"urgency":"Immediate",
|
218
|
-
"severity":"Severe",
|
219
|
-
"certainty":"Observed",
|
220
|
-
"headline":"LIQUID PETROLEOUM TANKER FIRE ON N2 INCOMING FREEWAY",
|
221
|
-
"description":"A liquid petroleoum tanker has caught fire on the N2 incoming freeway 1km
|
222
|
-
after the R300 interchange. Municipal fire fighting crews have been dispatched.
|
223
|
-
Traffic control officers are on the scene and have diverted traffic onto \nalternate routes."}]}
|
113
|
+
### Parsing an Alert From An External Source
|
114
|
+
|
115
|
+
RCAP can parse a CAP alert from a varierty of file formats. Besides the [standard XML](http://www.oasis-emergency.org/cap) representation, [YAML](http://yaml.org) and [JSON](http://json.org) support is also included.
|
116
|
+
|
117
|
+
To ensure the correct RCAP Alert object (RCAP::CAP_1_1::Alert or RCAP::CAP_1_2::Alert) is returned from an external source, a number of factories are defined in the RCAP::Alert module. If the version of the document to be parsed can not be ascertained a CAP 1.2 document will be assumed.
|
118
|
+
|
119
|
+
To parse an alert from a XML:
|
120
|
+
|
121
|
+
alert = RCAP::Alert.from_xml( xml_string )
|
122
|
+
|
123
|
+
### Validation
|
124
|
+
|
125
|
+
The RCAP API aims to codify as many of the rules of the CAP XML format into validation rules that can be checked using the Assistance API. The following Info object has two attributes ('severity' and 'certainty') set to incorrect values.
|
126
|
+
|
127
|
+
info = RCAP::CAP_1_2::Info.new do |info|
|
128
|
+
info.event = 'Liquid Petroleoum Tanker Fire'
|
129
|
+
info.language = 'en-ZA'
|
130
|
+
info.categories << Info::CATEGORY_TRANSPORT
|
131
|
+
info.urgency = Info::URGENCY_IMMEDIATE
|
132
|
+
info.severity = nil # Severity is not assigned
|
133
|
+
info.certainty = 'Incorrect Certainty' # Certainty is assigned an incorrect value
|
134
|
+
end
|
224
135
|
|
136
|
+
puts "Is info valid: #{ info.valid? }"
|
137
|
+
info.errors.full_messages.each{ |message| puts "Error: #{ message }" }
|
138
|
+
|
139
|
+
Will produce the following output:
|
140
|
+
|
141
|
+
Is info valid: false
|
142
|
+
Error: severity is not present
|
143
|
+
Error: certainty can only be assigned the following values: Observed, Likely, Possible, Unlikely, Unknown
|
225
144
|
|
226
|
-
|
145
|
+
All RCAP classes include the Validation module.
|
227
146
|
|
228
|
-
|
147
|
+
A full spec suite using [RSpec](http://www.rspec.info) was used to test the validations and currently numbers over 1000 tests.
|
148
|
+
|
149
|
+
Web resources
|
150
|
+
-------------
|
151
|
+
|
152
|
+
* The RCAP project page can be found at [http://www.aimred.com/projects/rcap](http://www.aimred.com/projects/rcap)
|
153
|
+
* The RCAP API docs can be found at [http://www.aimred.com/projects/rcap/api](http://www.aimred.com/projects/rcap/api)
|
154
|
+
* A public git repository can be found at [http://github.com/farrel/RCAP](http://github.com/farrel/RCAP)
|
155
|
+
* A CAP Validator based on RCAP can be found at [http://capvalidator.heroku.com](http://capvalidator.heroku.com)
|
229
156
|
|
230
157
|
Authors
|
231
158
|
-------
|
data/Rakefile
CHANGED
@@ -7,7 +7,7 @@ Bundler::GemHelper.install_tasks
|
|
7
7
|
|
8
8
|
YARD::Rake::YardocTask.new do |t|
|
9
9
|
t.files = ['lib/**/*.rb' ]
|
10
|
-
t.options += [ '--title', "RCAP Ruby
|
10
|
+
t.options += [ '--title', "RCAP - Common Alerting Protocol for Ruby" ]
|
11
11
|
t.options += [ '--main', 'README.md']
|
12
12
|
t.options += [ '--files', 'CHANGELOG.md' ]
|
13
13
|
t.options += [ '--output-dir', 'doc' ]
|
data/lib/rcap/alert.rb
CHANGED
@@ -10,7 +10,7 @@ module RCAP
|
|
10
10
|
# Initialise a RCAP Alert from a XML document.
|
11
11
|
#
|
12
12
|
# @param [IO,String] xml CAP alert in XML format. Can be a String or any IO object.
|
13
|
-
# @param [String] namespace_key The XML namespace that the CAP alert is in. If omitted
|
13
|
+
# @param [String] namespace_key The XML namespace that the CAP alert is in. If omitted
|
14
14
|
# the namespace of the document is inspected and a CAP_1_0::Alert, CAP_1_1::Alert
|
15
15
|
# or CAP_1_2::Alert is instantiated accordingly. If no namespace can be detected
|
16
16
|
# a CAP 1.2 message will be assumed.
|
@@ -66,7 +66,7 @@ module RCAP
|
|
66
66
|
#
|
67
67
|
# @param [Hash] hash Alert as a Ruby hash.
|
68
68
|
# @return [ RCAP::CAP_1_0::Alert, RCAP::CAP_1_1::Alert, RCAP::CAP_1_2::Alert ]
|
69
|
-
def self.from_h( hash )
|
69
|
+
def self.from_h( hash )
|
70
70
|
case hash[ JSON_CAP_VERSION_KEY ]
|
71
71
|
when CAP_1_0::Alert::CAP_VERSION
|
72
72
|
CAP_1_0::Alert.from_h( hash )
|