jss-api 0.6.1 → 0.6.2

data/lib/jss-api/api_object/peripheral.rb

@@ -1,335 +0,0 @@
-### Copyright 2016 Pixar
-###  
-###    Licensed under the Apache License, Version 2.0 (the "Apache License")
-###    with the following modification; you may not use this file except in
-###    compliance with the Apache License and the following modification to it:
-###    Section 6. Trademarks. is deleted and replaced with:
-###  
-###    6. Trademarks. This License does not grant permission to use the trade
-###       names, trademarks, service marks, or product names of the Licensor
-###       and its affiliates, except as required to comply with Section 4(c) of
-###       the License and to reproduce the content of the NOTICE file.
-###  
-###    You may obtain a copy of the Apache License at
-###  
-###        http://www.apache.org/licenses/LICENSE-2.0
-###  
-###    Unless required by applicable law or agreed to in writing, software
-###    distributed under the Apache License with the above modification is
-###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-###    KIND, either express or implied. See the Apache License for the specific
-###    language governing permissions and limitations under the Apache License.
-### 
-###
-
-###
-module JSS
-
-  #####################################
-  ### Module Variables
-  #####################################
-
-  #####################################
-  ### Module Methods
-  #####################################
-
-  #####################################
-  ### Classes
-  #####################################
-
-  ###
-  ### A peripheral in the JSS
-  ###
-  ### @see JSS::APIObject
-  ###
-  class Peripheral  < JSS::APIObject
-
-    #####################################
-    ### MixIns
-    #####################################
-
-    include JSS::Creatable
-    include JSS::Updatable
-
-    ### periphs have a purchasing subset
-    include JSS::Purchasable
-
-    ### periphs have a location subset, which will be
-    ### stored in primary attributes.
-    include JSS::Locatable
-
-    ### periphs can take uploaded files.
-    include JSS::Uploadable
-
-    #####################################
-    ### Class Methods
-    #####################################
-
-    #####################################
-    ### Class Constants
-    #####################################
-
-    ### The base for REST resources of this class
-    RSRC_BASE = "peripherals"
-
-    ### the hash key used for the JSON list output of all objects in the JSS
-    RSRC_LIST_KEY = :peripherals
-
-    ### The hash key used for the JSON object output.
-    ### It's also used in various error messages
-    RSRC_OBJECT_KEY = :peripheral
-
-    ### these keys, as well as :id and :name, are present in valid API JSON data for this class
-    VALID_DATA_KEYS = [:type, :bar_code_1, :computer_id ]
-
-
-    #####################################
-    ### Class Variables
-    #####################################
-
-    #####################################
-    ### Class Methods
-    #####################################
-
-    #####################################
-    ### Attributes
-    #####################################
-
-    ### @return [String] the type of peripheral
-    attr_reader :type
-
-    ### @return [String] the "bar code 1" value
-    attr_reader :bar_code_1
-    
-
-    ### @return [String] the "bar code 2" value
-    attr_reader :bar_code_2
-    
-
-    ### @return [Integer] the id number of the computer to which  this periph is connected
-    attr_reader :computer_id
-
-    #####################################
-    ### Instance Methods
-    #####################################
-
-    ###
-    ### @see APIObject
-    ###
-    def initialize (args = {})
-
-      ### periphs don't really have names, and the JSS module list method for
-      ### periphs gives the computer_id as the name, so give it a temp
-      ### name of "-1", which shouldn't ever exist in the JSS
-      args[:name] ||= "-1"
-
-      super
-
-      if args[:id] == :new
-        raise JSS::InvalidDataError, "New Peripherals must have a :type, which must be one of those defined in the JSS." unless args[:type]
-        @type = args[:type]
-        raise JSS::InvalidDataError, "No peripheral type '#{@type}' in the JSS" unless JSS::PeripheralType.all_names(:refresh).include? @type
-        @fields = {}
-        @rest_rsrc = 'peripherals/id/-1'
-        @site = "None"
-        return
-      end
-
-      @type =  @init_data[:general][:type]
-      @site = JSS::APIObject.get_name(@init_data[:general][:site])
-      @bar_code_1 = @init_data[:general][:bar_code_1]
-      @bar_code_2 = @init_data[:general][:bar_code_2]
-      @computer_id = @init_data[:general][:computer_id]
-
-      ### fill in the fields
-      @fields = {}
-      @init_data[:general][:fields].each{|f| @fields[f[:name]] = f[:value] }
-
-      ### get the field defs for this PeriphType, omitting the leading nil
-      @field_defs ||= JSS::PeripheralType.new(:name => @type).fields.compact
-
-      parse_location
-      parse_purchasing
-
-    end # initialize
-
-
-    ###
-    ### reset the restrsrc after creation
-    ###
-    ### @see JSS::Creatable#create
-    ###
-    def create
-      super
-      @rest_rsrc = "peripherals/id/#{@id}"
-      @id
-    end
-
-    ###
-    ### periphs don't have names
-    ###
-    def name= (newname)
-      raise JSS::UnsupportedError, "Peripherals don't have names."
-    end
-
-    ###
-    ###
-    ### @return [Hash] the field values of the peripheral
-    ###   Each key is the fields name, as a String
-    ###   and the value is the fields value, also as a String
-    ###
-    def fields
-      @fields
-    end
-
-    ###
-    ### Set the value of a field. It will be checked to ensure validity.
-    ###
-    ### @param field[String] the field to set
-    ###
-    ### @param value[String] the new value for the field
-    ###
-    ### @return [void]
-    ###
-    def set_field(field, value)
-      check_field(field, value)
-      @fields[field] = value
-      @need_to_update = true
-    end
-
-    ###
-    ### Set the value of barcode 1
-    ###
-    ### @param new_value[String] the new barcode value
-    ###
-    ### @return [void]
-    ###
-    def bar_code_1= (new_value)
-        @bar_code_1 = new_value
-        @need_to_update = true
-    end
-    
-
-    ###
-    ### Set the value of barcode 2
-    ###
-    ### @param new_value[String] the new barcode value
-    ###
-    ### @return [void]
-    ###
-    def bar_code_2= (new_value)
-        @bar_code_2 = new_value
-        @need_to_update = true
-    end
-    
-
-    ###
-    ### Associate this peripheral with a computer.
-    ###
-    ### @param computer[String,Integer] the name or id of a computer in the JSS
-    ###
-    ### @return [void]
-    ###
-    def associate(computer)
-      if computer =~ /^d+$/
-        raise JSS::NoSuchItemError, "No computer in the JSS with id #{computer}" unless JSS::Computer.all_ids.include? computer
-        @computer_id = computer
-      else
-        raise JSS::NoSuchItemError, "No computer in the JSS with name #{computer}" unless JSS::Computer.all_names.include? computer
-        @computer_id = JSS::Computer.map_all_ids_to(:name).invert[computer]
-      end
-      @need_to_update = true
-    end
-    
-
-    ###
-    ### Disassociate this peripheral from any computer.
-    ###
-    ### This seems to have no effect in the JSS,
-    ### the  computer/user/location data always shows the most recent.
-    ###
-    ### @return [void]
-    ###
-    def disassociate
-      @computer_id = nil
-      @need_to_update = true
-    end
-    
-
-    #################################
-    ### Private Methods below here
-    private
-
-    ###
-    ### check a field, the field name must match those defined in
-    ### the appropriate peripheral type.
-    ### If a field is a menu field, the value must also be one of those defined
-    ### in the periph type.
-    ### Raise an exception if wrong.
-    ###
-    def check_field(field, value)
-      ### get the field defs for this PeriphType, omitting the leading nil
-      @field_defs ||= JSS::PeripheralType.new(:name => @type).fields.compact
-
-      ### we must have the right number of fields, and they must have the same names
-      ### as the definition
-      required_fields = @field_defs.map{|f| f[:name]}
-      raise JSS::InvalidDataError, "Peripherals of type '#{@type}' doesn't have a field '#{field}', they only have: #{required_fields.join(', ')}" unless required_fields.include? field
-
-      ### any menu fields can only have values as defined by the type.
-      menu_flds = @field_defs.select{|f| f[:type] == "menu" }
-      menu_flds.each do |mf|
-        next unless mf[:name] == field
-        raise JSS::InvalidDataError, "The value for field '#{field}' must be one of: #{mf[:choices].join(', ')}" unless mf[:choices].include? value
-      end #if menu_flds.include? field
-
-    end # check fields
-
-    ###
-    ### Return the REST XML for this pkg, with the current values,
-    ### for saving or updating
-    ###
-    def rest_xml
-      doc = REXML::Document.new APIConnection::XML_HEADER
-      periph = doc.add_element RSRC_OBJECT_KEY.to_s
-
-      general = periph.add_element('general')
-      general.add_element('type').text = @type
-      general.add_element('site').add_element('name').text = @site
-      general.add_element('bar_code_1').text = @bar_code_1
-      general.add_element('bar_code_2').text = @bar_code_2
-      general.add_element('computer_id').text = @computer_id
-
-      fields = general.add_element('fields')
-      @fields.each do |n,v|
-        fld =  fields.add_element('field')
-        fld.add_element('name').text = n
-        fld.add_element('value').text = v
-      end
-
-      if has_location?
-        periph << location_xml
-      end
-      if has_purchasing?
-        periph << purchasing_xml
-      end
-
-      return doc.to_s
-    end # rest xml
-    
-    ### Aliases
-    alias barcode_1 bar_code_1
-    alias barcode1 bar_code_1
-    alias barcode_1= bar_code_1=
-    alias barcode1= bar_code_1=
-    
-    alias barcode_2 bar_code_2
-    alias barcode2 bar_code_2
-    alias barcode_2= bar_code_2=
-    alias barcode2= bar_code_2=
-    
-    alias assign_to associate
-    alias unassign disassociate
-    
-  end # class Peripheral
-end # module

data/lib/jss-api/api_object/peripheral_type.rb

@@ -1,295 +0,0 @@
-### Copyright 2016 Pixar
-###  
-###    Licensed under the Apache License, Version 2.0 (the "Apache License")
-###    with the following modification; you may not use this file except in
-###    compliance with the Apache License and the following modification to it:
-###    Section 6. Trademarks. is deleted and replaced with:
-###  
-###    6. Trademarks. This License does not grant permission to use the trade
-###       names, trademarks, service marks, or product names of the Licensor
-###       and its affiliates, except as required to comply with Section 4(c) of
-###       the License and to reproduce the content of the NOTICE file.
-###  
-###    You may obtain a copy of the Apache License at
-###  
-###        http://www.apache.org/licenses/LICENSE-2.0
-###  
-###    Unless required by applicable law or agreed to in writing, software
-###    distributed under the Apache License with the above modification is
-###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-###    KIND, either express or implied. See the Apache License for the specific
-###    language governing permissions and limitations under the Apache License.
-### 
-###
-
-###
-module JSS
-
-  #####################################
-  ### Classes
-  #####################################
-
-  ###
-  ### A peripheral_type in the JSS.
-  ###
-  ### A PeripheralType (as opposed to an individual {JSS::Peripheral}) is just an id, a name, and an Array of
-  ### Hashes describing the fields of data to be stored for peripherals of this type.
-  ###
-  ### See {#fields} for a desciption of how field definitions are stored.
-  ###
-  ### For manipulating the fields, see {#fields=}, {#set_field}, {#append_field}, {#prepend_field}, {#insert_field}, and {#delete_field}
-  ###
-  ### @see JSS::APIObject
-  ###
-  class PeripheralType  < JSS::APIObject
-
-    #####################################
-    ### MixIns
-    #####################################
-
-    include JSS::Creatable
-    include JSS::Updatable
-
-    #####################################
-    ### Class Methods
-    #####################################
-
-    #####################################
-    ### Class Constants
-    #####################################
-
-    ### The base for REST resources of this class
-    RSRC_BASE = "peripheraltypes"
-
-    ### the hash key used for the JSON list output of all objects in the JSS
-    RSRC_LIST_KEY = :peripheral_types
-
-    ### The hash key used for the JSON object output.
-    ### It's also used in various error messages
-    RSRC_OBJECT_KEY = :peripheral_type
-
-    ### these keys, as well as :id and :name,  are present in valid API JSON data for this class
-    VALID_DATA_KEYS = [:fields]
-
-    ### field types can be one of these, either String or Symbol
-    FIELD_TYPES = [:text, :menu]
-
-    #####################################
-    ### Attributes
-    #####################################
-
-    #####################################
-    ### Instance Methods
-    #####################################
-
-    ###
-    ### Initialize
-    ###
-    def initialize (args = {})
-
-      super
-
-      @fields = []
-      if @init_data[:fields]
-        @init_data[:fields].each{ |f|  @fields[f[:order]] = f }
-      end
-    end # initialize
-
-    ### The definitions of the fields stored for this peripheral type.
-    ###
-    ### Each Hash defines a field of data to store. The keys are:
-    ### - :name, String, the name of the field
-    ### - :type, String or Symbol, the kind of data to be stored in the field, either :text or :menu
-    ### - :choices, Array of Strings - if type is :menu, these are the menu choices.
-    ### - :order, the one-based index of this field amongst it's peers.
-    ###
-    ### Since Arrays are zero-based, and the field order is one-based, keeping
-    ### a nil at the front of the Array will keep the :order number in sync with the
-    ### Array index of each field definition. This is done automatically by the field-editing
-    ### methods: {#fields=}, {#set_field}, {#append_field}, {#prepend_field}, {#insert_field},
-    ### and {#delete_field}.
-    ###
-    ### So the Array from the API comes like this:
-    ###   [ {:type=>"text", :order=>1, :choices=>[], :name=>"make"},
-    ###     {:type=>"text", :order=>2, :choices=>[], :name=>"model"},
-    ###     {:type=>"text", :order=>3, :choices=>[], :name=>"family"},
-    ###     {:type=>"text", :order=>4, :choices=>[], :name=>"serialnum"} ]
-    ### But will be stored in a PeripheralType instance like this:
-    ###   [ nil,
-    ###     {:type=>"text", :order=>1, :choices=>[], :name=>"make"},
-    ###     {:type=>"text", :order=>2, :choices=>[], :name=>"model"},
-    ###     {:type=>"text", :order=>3, :choices=>[], :name=>"family"},
-    ###     {:type=>"text", :order=>4, :choices=>[], :name=>"serialnum"} ]
-    ###
-    ### therefore
-    ###   myPerifType.fields[2]
-    ### will get you the second field, which has :order => 2.
-    ###
-    ### @return [Array<Hash>] The field definitions
-    ###
-    def fields
-      @fields
-    end
-
-    ###
-    ### Replace the entire Array of field definitions.
-    ### The :order of each will be set based on the indexes of the
-    ### Array provided.
-    ###
-    ### @param new_fields[Array<Hash>] the new field definitions
-    ###
-    ### @return [void]
-    ###
-    def fields= (new_fields)
-      unless new_fields.kind_of? Array and  new_fields.reject{|c| c.kind_of? Hash }.empty?
-        raise JSS::InvalidDataError, "Argument must be an Array of Hashes."
-      end
-      raise "A peripheral type can have a maximmum of 20 fields"  if new_fields.count > 20
-      new_fields.each{ |f| field_ok? f }
-      @fields = new_fields
-      order_fields
-      @need_to_update = true
-    end
-
-    ###
-    ### Replace the details of one specific field.
-    ###
-    ### The order must already exist. Otherwise use
-    ### {#append_field}, {#prepend_field}, or {#insert_field}
-    ###
-    ### @param order[Integer] which field are we replacing?
-    ###
-    ### @param field[Hash] the new field data
-    ###
-    ### @return [void]
-    ###
-    def set_field(order, field = {})
-      raise JSS::NoSuchItemError, "No field with number '#{order}'. Use #append_field, #prepend_field, or #insert_field" unless @fields[order]
-      field_ok? field
-      @fields[order] = field
-      @need_to_update = true
-    end
-
-    ###
-    ### Add a new field to the end of the field list
-    ###
-    ### @param field[Hash] the new field data
-    ###
-    ### @return [void]
-    ###
-    def append_field(field = {})
-      field_ok? field
-      @fields << field
-      order_fields
-      @need_to_update = true
-    end
-
-    ###
-    ### Add a new field to the beginning of the field list
-    ###
-    ### @param field[Hash] the new field data
-    ###
-    ### @return [void]
-    ###
-    def prepend_field(field = {})
-      field_ok? field
-      @fields.unshift field
-      order_fields
-      @need_to_update = true
-    end
-
-    ###
-    ### Add a new field to the middle of the fields Array.
-    ###
-    ### @param order[Integer] where does the new field go?
-    ###
-    ### @param field[Hash] the new field data
-    ###
-    ### @return [void]
-    ###
-    def insert_field(order,field = {})
-      field_ok? field
-      @fields.insert((order -1), field)
-      order_fields
-      @need_to_update = true
-    end
-
-    ###
-    ### Remove a field from the array of fields.
-    ###
-    ### @param order[Integer] which field to remove?
-    ###
-    ### @return [void]
-    ###
-    def delete_field(order)
-      if @fields[order]
-        raise JSS::MissingDataError, "Fields can't be empty" if @fields.count == 1
-        @fields.delete_at index
-        order_fields
-        @need_to_update = true
-      end
-    end
-
-
-
-    ##############################
-    ### private methods
-    ##############################
-    private
-
-    ###
-    ### is a Hash of field data OK for use in the JSS?
-    ### Return true or raise an exception
-    ###
-    def field_ok?(field)
-      raise JSS::InvalidDataError, "Field elements must be hashes with :name, :type, and possibly :choices" unless field.kind_of? Hash
-      raise JSS::InvalidDataError, "Fields require names" if field[:name].to_s.empty?
-      raise JSS::InvalidDataError, "Fields :type must be one of: :#{FIELD_TYPES.join(', :')}" unless FIELD_TYPES.include? field[:type].to_sym
-
-      if field[:type].to_sym == :menu
-        unless field[:choices].kind_of? Array and  field[:choices].reject{|c| c.kind_of? String}.empty?
-          raise JSS::InvalidDataError, "Choices for menu fields must be an Array of Strings"
-        end # unless
-      else
-        field[:choices] = []
-      end # if type -- menu
-      true
-    end # def field ok?
-
-    ###
-    ### Close up gaps in the field order, and make each field's :order match it's array index
-    ###
-    def order_fields
-      @fields.compact!
-      @fields.each_index{|i| @fields[i][:order] = i+1}
-      @fields.unshift nil
-    end
-
-
-    ###
-    ###
-    ###
-    def rest_xml
-      order_fields
-      doc = REXML::Document.new APIConnection::XML_HEADER
-      pkg = doc.add_element RSRC_OBJECT_KEY.to_s
-      pkg.add_element('id').text = @id
-      pkg.add_element('name').text = @name
-      fields = pkg.add_element 'fields'
-
-      flds =  @fields.compact
-      flds.each_index do |i|
-        field = fields.add_element 'field'
-        field.add_element('order').text =flds[i][:order]
-        field.add_element('name').text = flds[i][:name]
-        field.add_element('type').text = flds[i][:type].to_s
-        choices = field.add_element('choices')
-        unless flds[i][:choices].empty?
-          flds[i][:choices].each{|c| choices.add_element('choice').text = c}
-        end
-      end # each index do i
-      return doc.to_s
-    end # rest xml
-
-  end # class Peripheral
-end # module