jss-api 0.6.1 → 0.6.2

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

@@ -1,98 +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
-  #####################################
-
-  #####################################
-  ### Sub-Modules
-  #####################################
-
-  ###
-  ### A mix-in module that allows objects to be created in the JSS
-  ### via the API.
-  ###
-  ### When a JSS::APIObject subclass includes this module, that subclass
-  ### can be instantiated with :id => :new, and :name => "some_new_name".
-  ###
-  ### The instance can be used to set desired values for the new object, and
-  ### once everything's good, use #create to create it in the JSS.
-  ###
-  ### If a Creatable object requires more data than just a :name for creation,
-  ### the subclass may want to redefine #initialize to require those data before
-  ### calling super.
-  ###
-  ### Some subclasses may want to redefine #create to check
-  ### the data for consistency, and then call super
-  ### (or they may have the individual setter methods do the checks)
-  ###
-  ### Classes mixing this module *must* provide a #rest_xml instance method that returns the XML
-  ### String to be submitted to the API for object creation.
-  ###
-  ### @see APIObject#save
-  ###
-  module Creatable
-
-    #####################################
-    ###  Constants
-    #####################################
-
-    CREATABLE = true
-
-    #####################################
-    ###  Variables
-    #####################################
-
-    #####################################
-    ###  Mixed-in Instance Methods
-    #####################################
-
-    ###
-    ### Create a new object in the JSS.
-    ###
-    ### @return [Integer] the jss ID of the newly created object
-    ###
-    def create
-      raise JSS::UnsupportedError, "Creating or editing #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless CREATABLE
-      raise AlreadyExistsError, "This #{self.class::RSRC_OBJECT_KEY} already exists. Use #update to make changes." if @in_jss
-      JSS::API.post_rsrc( @rest_rsrc, rest_xml) =~ /><id>(\d+)<\/id></
-      @id = $1.to_i
-      @in_jss = true
-      @need_to_update = false
-      @rest_rsrc =  "#{self.class::RSRC_BASE}/id/#{@id}"
-      return @id
-    end
-
-  end # module Creatable
-
-end # module

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

@@ -1,189 +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
-
-
-### A mix-in module providing consistent access to JSS::Criteriable::Criteria and
-### JSS::Criteriable::Criterion objects from within objects that contain Criteria.
-###
-###
-
-
-  #####################################
-  ### Module Variables
-  #####################################
-
-
-  #####################################
-  ### Module Methods
-  #####################################
-
-  #####################################
-  ### Sub-Modules
-  #####################################
-
-  ###
-  ### A mix-in module that allows objects to handle standardized search Criteria.
-  ###
-  ### Some objects in the JSS, such as Advanced Searches and Smart Groups,
-  ### include a set of Criteria. (i.e conditions which, when met, signify inclusion
-  ### in some result set.)
-  ###
-  ### A {JSS::Criteriable::Criteria} instance is a container for one or more
-  ### {JSS::Criteriable::Criterion} instances and provides methods for dealing with
-  ### them easily.
-  ###
-  ### When a {JSS::APIObject} subclass includes this module, that subclass
-  ### will have a :criteria attribute, which holds a {JSS::Criteriable::Criteria}
-  ### object and can be used to manipulate the Criterion objects inside.
-  ###
-  ### The including subclass also gains some instance methods:
-  ### * #parse_critera - sets up the :criteria attribute during initialization
-  ### * #criteria= - allows the wholesale replacement of the criteria
-  ### * #need_to_update - allows the {JSS::Criteriable::Criteria} instance to
-  ###   inform the subclass instance that it has changed and needs an #update
-  ###
-  ### Classes mixing in this module *must*
-  ### *  call #parse_criteria during initialization.
-  ### *  If they are Updatable or Creatable, they must insert
-  ###    self.criteria.rest_xml into their own xml output.
-  ###
-  ###
-  ### @example Working with the criteria of an advanced search
-  ###   # create a couple of Criterion instances
-  ###   crtn_0 = JSS::Criteriable::Criterion.new :and_or => :or, :name => "Username", :search_type => "is", :value => "jeauxbleaux"
-  ###   crtn_1 = JSS::Criteriable::Criterion.new :and_or => :and, :name => "Last Check-in", :search_type => "less than x days ago", :value => 3
-  ###
-  ###   # use them to create a Criteria instance
-  ###   crta = JSS::Criteriable::Criteria.new [crtn_0, crtn_1]
-  ###
-  ###   # create a new Advanced Search
-  ###   srch = JSS::AdvancedComputerSearch.new :id => :new, :name => "my computer search"
-  ###   srch.display_fields = ["Computer Name"]
-  ###
-  ###   # add our Criteria to it
-  ###   srch.criteria = crta
-  ###
-  ###   # create it in the JSS
-  ###   srch.create # srch.search_results now contains the matching computers
-  ###
-  ###   # append a new criterion to the criteria, limiting the search results farther
-  ###   srch.criteria.append_criterion JSS::Criteriable::Criterion.new(:and_or => :or, :name => "Computer Name", :search_type => "like", :value => "o")
-  ###
-  ###   # save the change to the JSS
-  ###   srch.save  # srch.search_results  now contains the matching computers
-  ###
-  ###   # oops - that last one should have been :and, not :or
-  ###   srch.criteria.criteria[2].and_or = :and
-  ###
-  ###   # the above can also be achieved like this, by replacing the last criterion altogether:
-  ###   srch.criteria.set_criterion 2, JSS::Criteriable::Criterion.new(:and_or => :and, :name => "Computer Name", :search_type => "like", :value => "o")
-  ###
-  ###   # save the change to the JSS
-  ###   srch.save  # srch.search_results  now contains the matching computers
-  ###
-  ### @see JSS::Criteriable::Criteria
-  ### @see JSS::Criteriable::Criterion
-  ###
-  module Criteriable
-
-    #####################################
-    ###  Constants
-    #####################################
-
-    CRITERIABLE = true
-
-
-    #####################################
-    ###  Variables
-    #####################################
-
-    #####################################
-    ###  Mixed-in Attributes
-    #####################################
-
-    ### @return [JSS::Criteriable::Criteria] the criteria for the instance into which we're mixed.
-    attr_reader :criteria
-
-    #####################################
-    ###  Mixed-in Instance Methods
-    #####################################
-
-    ###
-    ### During initialization, convert the @init_data[:criteria] Hash into
-    ### a JSS::Criteriable::Criteria instance stored in @criteria
-    ###
-    ### Classes mixing in this module must call this in #initialize
-    ###
-    ### @return [void]
-    ###
-    def parse_criteria
-      @criteria = if @init_data[:criteria]
-        JSS::Criteriable::Criteria.new @init_data[:criteria].map{|c| JSS::Criteriable::Criterion.new c}
-      else
-        nil
-      end
-      @criteria.container = self if @criteria
-    end
-
-    ###
-    ### Change the criteria, it must be a JSS::Criteriable::Criteria instance
-    ###
-    ### @param new_criteria[JSS::Criteriable::Criteria] the new criteria
-    ###
-    ### @return [void]
-    ###
-    def criteria= (new_criteria)
-      raise JSS::InvalidDataError, "JSS::Criteriable::Criteria instance required" unless new_criteria.kind_of?(JSS::Criteriable::Criteria)
-      @criteria = new_criteria
-      @criteria.container = self
-      @need_to_update = true
-    end
-
-    ###
-    ###
-    ### @api private
-    ### Allow our Criteria to tell us when there's been a change that needs
-    ### to be updated.
-    ###
-    ### @return [void]
-    ###
-    def should_update
-      @need_to_update = true if @in_jss
-    end
-
-    #####################################
-    ###  Mixed-in Class Methods
-    #####################################
-
-
-
-  end # module Criteriable
-
-end # module JSS
-
-require "jss-api/api_object/criteriable/criterion"
-require "jss-api/api_object/criteriable/criteria"

data/lib/jss-api/api_object/criteriable/criteria.rb

@@ -1,231 +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 Criteriable
-
-    #####################################
-    ### Module Variables
-    #####################################
-
-    #####################################
-    ### Module Methods
-    #####################################
-
-    #####################################
-    ### Classes
-    #####################################
-
-    ### This class stores an array of {JSS::Criteriable::Criterion} instances
-    ### and provides methods for working with them as a group.
-    ###
-    ### {JSS::APIObject} subclasses that include {JSS::Criteriable} have a :criteria attribute
-    ### which holds one Criteria object.
-    ###
-    ### Objects that contain Criteria objects need to
-    ### - call '#container = self' on their Criteria object when its created.
-    ### - implement #should_update, which the Criteria object calls when it changes.
-    ###
-    ### Both of those tasks are handled by the {JSS::Criteriable} module and are mixed in when
-    ### it's included.
-    ###
-    ### See {JSS::Criteriable} for examples
-    ###
-    class Criteria
-
-      #####################################
-      ### Class Constants
-      #####################################
-
-      ### Criterion instances we maintain need these attributes.s
-      CRITERION_ATTRIBUTES = [:priority, :and_or, :name, :search_type, :value]
-
-      #####################################
-      ### Attributes
-      #####################################
-
-      ### @return [Array] the group of JSS::Criteriable::Criterion instances making up these Criteria
-      attr_reader :criteria
-
-      ### @return [JSS::APIObject subclass] a reference to the object containing these Criteria
-      attr_reader :container
-
-      ###
-      ### @param new_criteria[Array<JSS::Criteriable::Criterion>]
-      ###
-      def initialize(new_criteria)
-        @criteria = []
-        self.criteria = new_criteria
-      end # init
-
-      ### set the object we belong to, so we can set its @should_update value
-      def container= (a_thing)
-        @container = a_thing
-      end
-
-      ###
-      ### Provide a whole new array of JSS::Criteriable::Criterion instances for this Criteria
-      ###
-      ### @param new_criteria[Array<JSS::Criteriable::Criterion>]
-      ###
-      ### @return [void]
-      ###
-      def criteria= (new_criteria)
-        unless new_criteria.kind_of? Array and  new_criteria.reject{|c| c.kind_of? JSS::Criteriable::Criterion }.empty?
-          raise JSS::InvalidDataError, "Argument must be an Array of JSS::Criteriable::Criterion instances."
-        end
-        new_criteria.each{ |nc| criterion_ok? nc }
-        @criteria = new_criteria
-        set_priorities
-        @container.should_update if @container
-      end
-
-      ###
-      ### Add a new criterion to the end of the criteria
-      ###
-      ### @param criterion[JSS::Criteriable::Criterion] the new Criterion to store
-      ###
-      ### @return [void]
-      ###
-      def append_criterion(criterion)
-        criterion_ok? criterion
-        criterion.priority = @criteria.length
-        @criteria << criterion
-        @container.should_update if @container
-      end
-
-      ###
-      ### Add a new criterion to the beginning of the criteria
-      ###
-      ### @param criterion[JSS::Criteriable::Criterion] the new Criterion to store
-      ###
-      ### @return [void]
-      ###
-      def prepend_criterion(criterion)
-        criterion_ok? criterion
-        @criteria.unshift criterion
-        set_priorities
-        @container.should_update if @container
-      end
-
-      ###
-      ### Add a new criterion to the middle of the criteria
-      ###
-      ### @param priority[Integer] the priority/index before which to insert the new one.
-      ###
-      ### @param criterion[JSS::Criteriable::Criterion] the new Criterion to store at that index
-      ###
-      ### @return [void]
-      ###
-      def insert_criterion(priority,criterion)
-        criterion_ok? criterion
-        @criteria.insert criterion[:priority], criterion
-        set_priorities
-        @container.should_update if @container
-      end
-
-      ###
-      ### Remove a criterion from the criteria
-      ###
-      ### @param priority[Integer] the priority/index of the criterion to delete
-      ###
-      ### @return [void]
-      ###
-      def delete_criterion(priority)
-        if @criteria[priority]
-          raise JSS::MissingDataError, "Criteria can't be empty" if @criteria.count == 1
-          @criteria.delete_at priority
-          set_priorities
-        end
-        @container.should_update if @container
-      end
-
-      ###
-      ### Change the details of one specific criterion
-      ###
-      ### @param priority[Integer] the priority/index of the criterion being changed.
-      ###   The index must already exist. Otherwise use
-      ###   #append_criterion, #prepend_criterion, or #insert_criterion
-      ###
-      ### @param criterion[JSS::Criteriable::Criterion] the new Criterion to store at that index
-      ###
-      ### @return [void]
-      ###
-      def set_criterion(priority, criterion)
-        raise JSS::NoSuchItemError, "No current criterion with priority '#{priority}'" unless @criteria[priority]
-        criterion_ok? criterion
-        @criteria[priority] = criterion
-        set_priorities
-        @container.should_update if @container
-      end
-
-      ###
-      ### Set the priorities of the @criteria to match their array indices
-      ###
-      ### @return [void]
-      ###
-      def set_priorities
-        @criteria.each_index{ |ci| @criteria[ci].priority = ci }
-      end
-
-      ###
-      ### @return [REXML::Element] the xml element for the criteria
-      ###
-      ### @note This can't be a private method for this class since container classes must call it
-      ###
-      ### @api private
-      ###
-      def rest_xml
-        raise JSS::MissingDataError, "Criteria can't be empty" if @criteria.empty?
-        cr = REXML::Element.new 'criteria'
-        @criteria.each { |c| cr << c.rest_xml }
-        return cr
-     end # rest_xml
-
-      #####################################
-      ### Private Instance Methods
-      #####################################
-      private
-
-
-      ###
-      ### Chech the validity of a criterion.
-      ### Note that this doesn't check the :priority
-      ### which is set by methods calling this one.
-      ###
-      ### Return true or raise an error about the problem
-      ###
-      def criterion_ok? (criterion)
-        raise JSS::InvalidDataError, "Duplicate criterion: #{criterion.signature.join(', ')}" if @criteria.select{|c| c == criterion}.count > 1
-        raise JSS::InvalidDataError, "Missing :and_or for criterion: #{criterion.signature.join(', ')}" unless criterion.and_or
-        raise JSS::InvalidDataError, "Missing :name for criterion: #{criterion.signature.join(', ')}" unless criterion.name
-        raise JSS::InvalidDataError, "Missing :search_type for criterion: #{criterion.signature.join(', ')}" unless criterion.search_type
-        raise JSS::InvalidDataError, "Missing :value for criterion: #{criterion.signature.join(', ')}" unless criterion.value
-        true
-      end
-
-    end # class Criteria
-  end # module Criteriable
-end # module