jss-api 0.5.4

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

@@ -0,0 +1,98 @@
+### Copyright 2014 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

@@ -0,0 +1,189 @@
+### Copyright 2014 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

@@ -0,0 +1,231 @@
+### Copyright 2014 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