Class: NcsNavigator::Warehouse::XmlEmitter

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/ncs_navigator/warehouse/xml_emitter.rb

Overview

Generates VDR XML from a warehouse instance. This is the object which implements the emit-xml tool in the mdes-wh command line client.

Constant Summary collapse

HEADER_TEMPLATE = 
ERB.new(<<-XML_ERB)
<?xml version="1.0" encoding="UTF-8" ?>
<!--
  This document was generated by
  NCS Navigator MDES Warehouse #{NcsNavigator::Warehouse::VERSION}
-->
<ncs:recruitment_substudy_transmission_envelope
  xmlns:ncs="http://www.nationalchildrensstudy.gov"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  >
<ncs:transmission_header>
<sc_id><%= sc_id %></sc_id>
<psu_id><%= psu_id %></psu_id>
<specification_version><%= specification_version %></specification_version>
<is_snapshot>true</is_snapshot>
</ncs:transmission_header>
<ncs:transmission_tables>
XML_ERB
<<-XML
</ncs:transmission_tables>
</ncs:recruitment_substudy_transmission_envelope>
XML

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(config, filename, options = {}) ⇒ XmlEmitter

Create a new NcsNavigator::Warehouse::XmlEmitter.

:content is not specified. If the option is not specified at all, the in the configuration Configuration#default_xml_filter_set will be used, if any. To avoid using even this default, include :filters=>nil in the options.

Parameters:

  • config (Configuration) —

    the configuration for the warehouse from which to emit records.

  • filename (Pathname, #to_s, nil) —

    the filename to which the output will be written. If nil, the default_filename is used.

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :include-pii (Boolean) — default: false —

    should PII variable values be included in the XML?

  • :zip (Boolean) — default: true —

    should a ZIP file be produced alongside the XML file?

  • :content (Enumerable) —

    an enumerable over the records to emit. A Contents will be created using the other options if this is not specified.

  • :block-size (Fixnum) — default: 5000 —

    the maximum number of records to load into memory before writing them to the XML file. Reduce this to reduce the memory load of the emitter. Increasing it will probably not improve performance, even if you have sufficient memory to load more records. Only used if :content is not specified.

  • :tables (Array<#to_s>) — default: all for current MDES version —

    the tables to include in the emitted XML. Only used if :content is not specified.

  • :filters (Array<#to_sym>, nil) — default: config.default_xml_filter_set —

    named filter sets to apply to the data before emitting XML. Only used if



107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/ncs_navigator/warehouse/xml_emitter.rb', line 107

def initialize(config, filename, options={})
  @configuration = config
  @zip = options.has_key?(:zip) ? options[:zip] : true

  @xml_files = determine_files_to_create(filename, options)

  @tracker = ProgressTracker.new(@configuration)

  if options[:content]
    @content_enumerator = options[:content]
  else
    filter_names =
      if options.has_key?(:filters)
        options[:filters] ? options[:filters] : []
      else
        [config.default_xml_filter_set].compact
      end
    filters =
      unless filter_names.empty?
        filter_names.collect { |n| config.filter_set(n) }
      end

    @content_enumerator = Contents.new(config, {
      :tables => options[:tables],
      :'block-size' => options[:'block-size'],
      :filters => filters
    })
  end
end

Instance Attribute Details

#configuration ⇒ Configuration (readonly)

Returns the warehouse configuration used by this emitter.

Returns:

  • (Configuration) —

    the warehouse configuration used by this emitter.



20
21
22
 
# File 'lib/ncs_navigator/warehouse/xml_emitter.rb', line 20

def configuration
  @configuration
end

Class Method Details

.default_filename(configuration, include_pii = false) ⇒ Pathname

Returns the default filename to use for a VDR XML submission. The format is {county}-{YYYYMMDD}{-PII}.xml.

Parameters:

Returns:

  • (Pathname) —

    the default filename to use for a VDR XML submission. The format is {county}-{YYYYMMDD}{-PII}.xml.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/ncs_navigator/warehouse/xml_emitter.rb', line 58

def self.default_filename(configuration, include_pii=false)
  psu_type = configuration.mdes.types.detect { |type| type.name =~ /^psu_cl/ }
  unless psu_type
    fail 'Cannot find the PSU code list. Please specify a filename manually.'
  end

  psu_id = configuration.navigator.psus.first.id
  psu_entry =  psu_type.code_list.detect { |cle| cle.value == psu_id }
  unless psu_entry
    fail "Cannot find PSU #{psu_id} in #{psu_type.name}. Please specify a filename manually."
  end

  Pathname.new '%s-%s%s.xml' % [
    psu_entry.label.split(',', 2).first.downcase.gsub(/\s*county\s*/, '').strip.gsub(' ', '_'),
    Time.now.iso8601.split('T').first.gsub('-', ''),
    include_pii ? '-PII' : ''
  ]
end

Instance Method Details

#emit_xml

This method returns an undefined value.

Emit XML from the configured warehouse to #filename.



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/ncs_navigator/warehouse/xml_emitter.rb', line 150

def emit_xml
  shell.say_line("Exporting to #{xml_files.collect(&:describe).join(', ')}")
  log.info("Beginning XML export to #{xml_files.collect(&:describe).join(', ')}")

  @tracker.start!
  xml_files.each { |xf| xf.write HEADER_TEMPLATE.result(binding) }
  @content_enumerator.each do |instance|
    @tracker.starting_instance(instance)
    xml_files.each { |xf| xf.write_instance(instance) }
    @tracker.finish_instance(instance)
  end
  xml_files.each { |xf| xf.write FOOTER_TEMPLATE }
  xml_files.each { |xf| xf.close }
  @tracker.stop!

  xml_files.each { |xf| xf.zip_if_desired }
  log.info("XML export complete")
end

#filename ⇒ Pathname

Returns the single file to which the XML will be emitted. Throws an exception if writing to multiple files.

Returns:

  • (Pathname) —

    the single file to which the XML will be emitted. Throws an exception if writing to multiple files.



172
173
174
175
176
177
178
 
# File 'lib/ncs_navigator/warehouse/xml_emitter.rb', line 172

def filename
  if xml_files.size == 1
    xml_files.first.filename
  else
    fail "Emitting more than one file. Use `xml_files` to interrogate."
  end
end

#include_pii? ⇒ Boolean

Returns Will PII be included in the exported XML? Throws an exception if writing to multiple files.

Returns:

  • (Boolean) —

    Will PII be included in the exported XML? Throws an exception if writing to multiple files.



183
184
185
186
187
188
189
 
# File 'lib/ncs_navigator/warehouse/xml_emitter.rb', line 183

def include_pii?
  if xml_files.size == 1
    xml_files.first.include_pii?
  else
    fail "Emitting more than one file. Use `xml_files` to interrogate."
  end
end

#models ⇒ Array<Models::MdesModel>

Returns the models whose data will be emitted. This is determined from the :tables option to #initialize or by any models method implemented by the value passed to the :content option.

Returns:

  • (Array<Models::MdesModel>) —

    the models whose data will be emitted. This is determined from the :tables option to #initialize or by any models method implemented by the value passed to the :content option.



142
143
144
 
# File 'lib/ncs_navigator/warehouse/xml_emitter.rb', line 142

def models
  @content_enumerator.models if @content_enumerator.respond_to?(:models)
end

#zip? ⇒ Boolean

Will ZIP archive(s) be created along with the XML?

Returns:

  • (Boolean) 


195
196
197
 
# File 'lib/ncs_navigator/warehouse/xml_emitter.rb', line 195

def zip?
  @zip
end