jss-api 0.5.4

data/lib/jss-api/db_connection.rb

@@ -0,0 +1,243 @@
+### 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
+  #####################################
+
+  #####################################
+  ### Classes
+  #####################################
+
+  ###
+  ### A mysql connection to the JSS database.
+  ###
+  ### This is a singleton class, only one can exist at a time, and it
+  ### is created, but not connected, automatically when the module loads.
+  ###
+  ### Use it via the JSS::DB_CNX constant (for connection metadata)
+  ### and the JSS::DB_CNX.db attribute (which contains the actual mysql
+  ### query interface) for making queries
+  ###
+  ### Direct MySQL access is minimal and discouraged, since it
+  ### bypasses the API, and can be very dangerous. However, it's necessary
+  ### to overcome some limitations of the API or to access custom tables.
+  ###
+  ### While a database connction isn't required for most things,
+  ### warnings will be sent to stderr when functionality is limited due to
+  ### a lack of a database connection i.e. when JSS::DB_CNX.connected? == false
+  ###
+  ### To make a connection with credentials, just call the #connect method thus:
+  ###    JSS::DB_CNX.connect :server => 'server.company.com', :user => "user", :pw => "pw"
+  ###
+  ### Other options include:
+  ###   :db_name => which database to connect to, defaults to 'jamfsoftware'
+  ###   :port => tcp port for connection to server, defaults to the standard mysql port.
+  ###   :connect_timeout => seconds to wait before giving up on connection, defaults to 120
+  ###   :read_timeout => seconds to wait before giving up on recieving data, defaults to 120
+  ###   :write_timeout => seconds to wait before giving up on sending data, defaults to 120
+  ###   :timeout => sets all three timeouts to the same value, defaults to 120
+  ###
+  ### Calling JSS::DB_CNX.connect again will re-use any values not provided.
+  ### but will create a new connection.
+  ###
+  class DBConnection
+
+    include Singleton
+
+    #####################################
+    ### Class Constants
+    #####################################
+
+    ### The name of the JSS database on the mysql server
+    DEFAULT_DB_NAME = "jamfsoftware"
+
+    ### give the connection a 120 second timeout, for really slow
+    ### net connections (like... from airplanes)
+    DFT_TIMEOUT = 120
+
+    ###
+    DFT_SOCKET = '/var/mysql/mysql.sock'
+
+    ### the strftime format for reading/writing dates in the db
+    SQL_DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+
+
+    attr_reader :server
+    attr_reader :port
+    attr_reader :socket
+    attr_reader :user
+    attr_reader :db_name
+    attr_reader :connect_timeout
+    attr_reader :read_timeout
+    attr_reader :write_timeout
+    attr_reader :connected
+
+
+    def initialize ()
+      require 'mysql'
+      @mysql = Mysql.init
+      @connected = false
+    end #init
+
+    ###
+    ### Connect to the JSS MySQL database.
+    ###
+    ### @param args[Hash] the keyed arguments for connection.
+    ###
+    ### @option args :server[String] Required, the hostname of the JSS API server
+    ###
+    ### @option args :port[Integer] the port number to connect with, defaults to the default Mysql TCP port
+    ###
+    ### @option args :socket[String,Pathname] when the server is 'localhost', the path to the connection socket.
+    ###
+    ### @option args :db_name[String] the name of the database to use, defaults to 'jamfsoftware'
+    ###
+    ### @option args :user[String] Required, the mysql user to connect as
+    ###
+    ### @option args :pw[String,Symbol] Required, the password for that user, or :prompt, or :stdin
+    ###   If :prompt, the user is promted on the commandline to enter the password for the :user.
+    ###   If :stdin#, the password is read from a line of std in represented by the digit at #,
+    ###   so :stdin3 reads the passwd from the third line of standard input. defaults to line 2,
+    ###   if no digit is supplied. see {JSS.stdin}
+    ###
+    ### @option args :connect_timeout[Integer] the number of seconds to wait for an initial response, defaults to 120
+    ###
+    ### @option args :read_timeout[Integer] the number of seconds before read-request times out, defaults to 120
+    ###
+    ### @option args :write_timeout[Integer] the number of seconds before write-request times out, defaults to 120
+    ###
+    ### @option args :timeout[Integer] used for any of the timeouts that aren't explicitly set.
+    ###
+    ### @return [true] the connection was successfully made.
+    ###
+    def connect(args = {})
+
+      # settings from config if they aren't in the args
+      args[:server] ||= JSS::CONFIG.db_server_name
+      args[:port] ||= JSS::CONFIG.db_server_port
+      args[:socket] ||= JSS::CONFIG.db_server_socket
+      args[:db_name] ||= JSS::CONFIG.db_name
+      args[:user] ||= JSS::CONFIG.db_username
+      args[:connect_timeout] ||= JSS::CONFIG.db_connect_timeout
+      args[:read_timeout] ||= JSS::CONFIG.db_read_timeout
+      args[:write_timeout] ||= JSS::CONFIG.db_write_timeout
+
+      ### if one timeout was given, use it for all three
+      args[:connect_timeout] ||= args[:timeout]
+      args[:read_timeout] ||= args[:timeout]
+      args[:write_timeout] ||= args[:timeout]
+
+      ### if these weren't given, use the defaults
+      args[:connect_timeout] ||= DFT_TIMEOUT
+      args[:read_timeout] ||= DFT_TIMEOUT
+      args[:write_timeout] ||= DFT_TIMEOUT
+      args[:port] ||= Mysql::MYSQL_TCP_PORT
+      args[:socket] ||= DFT_SOCKET
+      args[:db_name] ||= DEFAULT_DB_NAME
+
+      @mysql.close if connected?
+
+      @server = args[:server]
+      @port = args[:port]
+      @socket = args[:socket]
+      @mysql_name = args[:db_name]
+      @user = args[:user]
+      @connect_timeout = args[:connect_timeout]
+      @read_timeout = args[:read_timeout]
+      @write_timeout = args[:write_timeout]
+
+      # make sure we have a user
+      raise JSS::MissingDataError, "No JSS user specified, or listed in configuration." unless args[:user]
+
+      # passwd from prompt, stdin, or args?
+      raise JSS::MissingDataError, "Missing :pw (or :prompt/:stdin) for user '#{@user}'" unless args[:pw]
+
+      @pw = if args[:pw] == :prompt
+        JSS.prompt_for_password "Enter the password for the MySQL user '#{@user}':"
+      elsif  args[:pw].is_a?(Symbol) and args[:pw].to_s.start_with?('stdin')
+        args[:pw].to_s =~ /^stdin(\d+)$/
+        line = $1
+        line ||= 2
+        JSS.stdin line
+      else
+        args[:pw]
+      end
+
+
+
+      @mysql = Mysql.init
+
+      @mysql.options Mysql::OPT_CONNECT_TIMEOUT, @connect_timeout
+      @mysql.options Mysql::OPT_READ_TIMEOUT, @read_timeout
+      @mysql.options Mysql::OPT_WRITE_TIMEOUT, @write_timeout
+
+      @mysql.connect @server, @user , @pw , @mysql_name, @port, @socket
+
+      @connected = true
+    end # reconnect
+
+    ###
+    ### @return [Mysql] The mysql database connection itself
+    ###
+    def db
+      raise JSS::InvalidConnectionError, "No database connection. Please use JSS::DB_CNX.connect" unless JSS::DB_CNX.connected?
+      @mysql
+    end
+
+    ###
+    ### close the connection to the database
+    ### it'll have to be re-connected before using again
+    ###
+    def disconnect
+      @mysql.close if connected?
+      @connected = false
+      nil
+    end # disconnect
+
+    #### Aliases
+
+    alias connected? connected
+
+  end # class DBConnection
+
+  ### The single instance of the DBConnection
+  DB_CNX = DBConnection.instance
+
+  ###
+  ### @return [Mysql] The mysql database available through the DBConnection.instance
+  ###
+  def self.db
+    DB_CNX.db
+  end
+
+end # module
+
+

data/lib/jss-api/exceptions.rb

@@ -0,0 +1,83 @@
+### 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
+  
+  #####################################
+  ### Exceptions
+  #####################################
+  
+  ### 
+  ### MissingDataError - raise this error when we 
+  ### are missing args, or other simliar stuff.
+  ### 
+  class MissingDataError < RuntimeError; end
+  
+  ### 
+  ### InvalidDataError - raise this error when 
+  ### a data item isn't what we expected.
+  ### 
+  class InvalidDataError < RuntimeError; end
+  
+  ### 
+  ### InvalidConnectionError - raise this error when we 
+  ### don't have a usable connection to a network service, or
+  ### don't have proper authentication/authorization.
+  ### 
+  class InvalidConnectionError < RuntimeError; end
+  
+  ### 
+  ### NoSuchItemError - raise this error when 
+  ### a desired item doesn't exist.
+  ### 
+  class NoSuchItemError < RuntimeError; end
+  
+  ### 
+  ### AlreadyExistsError - raise this error when 
+  ### trying to create something that already exists.
+  ### 
+  class AlreadyExistsError < RuntimeError; end
+  
+  ### 
+  ### FileServiceError - raise this error when 
+  ### there's a problem accessing file service on a
+  ### distribution point.
+  ### 
+  class FileServiceError < RuntimeError; end
+  
+  ###
+  ### UnmanagedError - raise this when we 
+  ### try to do something managerial to 
+  ### an unmanaged object
+  ###
+  class UnmanagedError <  RuntimeError; end
+  
+  ###
+  ### UnsupportedError - raise this when we 
+  ### try to do something not yet supported
+  ###
+  class UnsupportedError <  RuntimeError; end
+  
+end # module JSS

data/lib/jss-api/ruby_extensions.rb

@@ -0,0 +1,35 @@
+### 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.
+### 
+###
+
+### All monkey-patched convenience methods are either prefixed with "jss_"  or 
+### if they are type coercions, "to_jss_"
+###
+
+###
+require "jss-api/ruby_extensions/filetest.rb"
+require "jss-api/ruby_extensions/hash.rb"
+require "jss-api/ruby_extensions/ipaddr.rb"
+require "jss-api/ruby_extensions/pathname.rb"
+require "jss-api/ruby_extensions/time.rb"
+require "jss-api/ruby_extensions/string.rb"

data/lib/jss-api/ruby_extensions/filetest.rb

@@ -0,0 +1,43 @@
+### 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 FileTest
+  #############################################
+  ### FileTest.file? returns true if
+  ### the item is a symlink pointing to a regular file.
+  ###
+  ### This test, real_file?, returns true if the item is
+  ### a regular file but NOT a symlink.
+  ###
+  def FileTest.jss_real_file?(path)
+    FileTest.file?(path) and not FileTest.symlink?(path)
+  end # real_file?
+end # module FileTest
+
+
+
+
+
+

data/lib/jss-api/ruby_extensions/hash.rb

@@ -0,0 +1,79 @@
+### 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.
+### 
+###
+
+###
+class Hash
+
+  ###
+  ### Convert Hash values to nil.
+  ###
+  ### With no block, values equalling the String, or any member of the Array, given
+  ### will be converted to nil. Equality is evaluated with == and Array#include?
+  ###
+  ### With a block, if the result of the block evaluates to true, the value is converted to nil.
+  ###
+  ### Subhashes are ignored unless recurse is true.
+  ###
+  ### @param to_nils[String,Array] Hash values equal to (==) these become nil. Defaults to empty string
+  ###
+  ### @param recurse[Boolean] should sub-Hashes be nillified?
+  ###
+  ### @yield [value] Hash values for which the block returns true will become nil.
+  ###
+  ### @return [Hash] the hash with the desired values converted to nil
+  ###
+  ### @example
+  ###   hash = {:foo => '', :bar => {:baz => '' }}
+  ###   hash.jss_nillify!  # {:foo => nil, :bar => {:baz => '' }}
+  ###
+  ###   hash = {:foo => '', :bar => {:baz => '' }}
+  ###   hash.jss_nillify! '', :recurse  # {:foo => nil, :bar => {:baz => nil }}
+  ###
+  ###   hash = {:foo => 123, :bar => {:baz => '', :bim => "123" }}
+  ###   hash.jss_nillify! ['', 123], :recurse # {:foo => nil, :bar => {:baz => nil, :bim => "123" }}
+  ###
+  ###   hash = {:foo => 123, :bar => {:baz => '', :bim => "123" }}
+  ###   hash.jss_nillify!(:anything, :recurse){|v| v.to_i == 123 }  # {:foo => nil, :bar => {:baz => '', :bim => nil }}
+  ###
+  def jss_nillify!(to_nils = '', recurse = false, &block )
+
+    nillify_these = [] << to_nils
+    nillify_these.flatten!
+
+    self.each_pair do |k,v|
+      if v.class == Hash
+        v.jss_nillify!(to_nils, recurse, &block)
+        next
+      end
+      do_it = if block_given?
+        yield v
+      else
+        nillify_these.include? v
+      end
+      self[k] = nil if do_it
+    end # each pair
+  end # def nillify
+end # class
+
+