ruby-jss 1.6.4 → 2.0.0a10

data/lib/{jss → jamf}/db_connection.rb

@@ -1,4 +1,4 @@
-### Copyright 2020 Pixar
+### Copyright 2022 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -23,25 +23,18 @@
 ###
 ###
 
-###
-module JSS
-
-  #####################################
-  ### Module Variables
-  #####################################
+require 'mysql'
 
-  #####################################
-  ### Classes
-  #####################################
+###
+module Jamf
 
-  ###
   ### 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
+  ### Use it via the Jamf::DB_CNX constant (for connection metadata)
+  ### and the Jamf::DB_CNX.db attribute (which contains the actual mysql
   ### query interface) for making queries
   ###
   ### Direct MySQL access is minimal and discouraged, since it
@@ -50,10 +43,10 @@ module JSS
   ###
   ### 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
+  ### a lack of a database connection i.e. when Jamf::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"
+  ###    Jamf::DB_CNX.connect :server => 'server.company.com', :user => "user", :pw => "pw"
   ###
   ### Other options include:
   ###   :db_name => which database to connect to, defaults to 'jamfsoftware'
@@ -63,7 +56,7 @@ module JSS
   ###   :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.
+  ### Calling Jamf::DB_CNX.connect again will re-use any values not provided.
   ### but will create a new connection.
   ###
   class DBConnection
@@ -104,7 +97,6 @@ module JSS
     attr_reader :connected
 
     def initialize
-      require 'mysql'
       @mysql = Mysql.init
       @connected = false
     end # init
@@ -140,7 +132,7 @@ module JSS
     ###
     ### @return [true] the connection was successfully made.
     ###
-    def connect(args = {})
+    def connect(**args)
       begin
         disconnect if @connected
       rescue Mysql::ClientError::ServerGoneError
@@ -153,13 +145,13 @@ module JSS
       @server = args[:server] ? args[:server] : hostname
 
       # settings from config if they aren't in the args
-      args[:port] ||= JSS::CONFIG.db_server_port ? JSS::CONFIG.db_server_port : Mysql::MYSQL_TCP_PORT
-      args[:socket] ||= JSS::CONFIG.db_server_socket ? JSS::CONFIG.db_server_socket : DFT_SOCKET
-      args[:db_name] ||= JSS::CONFIG.db_name ? JSS::CONFIG.db_name : DEFAULT_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
+      args[:port] ||= Jamf.config.db_server_port ? Jamf.config.db_server_port : Mysql::MYSQL_TCP_PORT
+      args[:socket] ||= Jamf.config.db_server_socket ? Jamf.config.db_server_socket : DFT_SOCKET
+      args[:db_name] ||= Jamf.config.db_name ? Jamf.config.db_name : DEFAULT_DB_NAME
+      args[:user] ||= Jamf.config.db_username
+      args[:connect_timeout] ||= Jamf.config.db_connect_timeout
+      args[:read_timeout] ||= Jamf.config.db_read_timeout
+      args[:write_timeout] ||= Jamf.config.db_write_timeout
       args[:charset] ||= DFT_CHARSET
 
       ### if one timeout was given, use it for all three
@@ -176,9 +168,9 @@ module JSS
       @write_timeout = args[:write_timeout]
 
       # make sure we have a user, pw, server
-      raise JSS::MissingDataError, 'No MySQL user specified, or defined in configuration.' unless args[:user]
-      raise JSS::MissingDataError, "Missing :pw (or :prompt/:stdin) for user '#{@user}'" unless args[:pw]
-      raise JSS::MissingDataError, 'No MySQL Server hostname specified, or listed in configuration.' unless @server
+      raise Jamf::MissingDataError, 'No MySQL user specified, or defined in configuration.' unless args[:user]
+      raise Jamf::MissingDataError, "Missing :pw (or :prompt/:stdin) for user '#{@user}'" unless args[:pw]
+      raise Jamf::MissingDataError, 'No MySQL Server hostname specified, or listed in configuration.' unless @server
 
       @pw = if args[:pw] == :prompt
               JSS.prompt_for_password "Enter the password for the MySQL user #{@user}@#{@server}:"
@@ -210,7 +202,7 @@ module JSS
     ### @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?
+      raise Jamf::InvalidConnectionError, 'No database connection. Please use Jamf::DB_CNX.connect' unless Jamf::DB_CNX.connected?
       @mysql
     end
 
@@ -272,9 +264,9 @@ module JSS
       # return it if already set
       return @server if @server
       # otherwise, from the config
-      srvr = JSS::CONFIG.db_server_name
+      srvr = Jamf.config.db_server_name
       # otherwise, assume its on the JSS server to which this client talks
-      srvr ||= JSS::Client.jss_server
+      srvr ||= Jamf::Client.jss_server
       srvr
     end
 

data/lib/{jpapi.rb → jamf/deprecations/deprecated_api_constant.rb}

@@ -1,4 +1,4 @@
-# Copyright 2020 Pixar
+# Copyright 2022 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -20,7 +20,6 @@
 #    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.
-#
-#
 
-require 'jamf'
+# @deprecated Use Jamf.cnx to access the module-wide default connection
+Jamf::API = Jamf.cnx

data/lib/jamf/deprecations/deprecated_config_constant.rb

@@ -0,0 +1,25 @@
+# Copyright 2022 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.
+
+# @deprecated Use Jamf.config to access the module-wide config settings
+Jamf::CONFIG = Jamf.config

data/lib/jamf/exceptions.rb

@@ -1,4 +1,4 @@
-# Copyright 2020 Pixar
+# Copyright 2022 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -23,7 +23,6 @@
 #
 #
 
-# The Module
 module Jamf
 
   # Exceptions
@@ -55,6 +54,11 @@ module Jamf
   #
   class AlreadyExistsError < RuntimeError; end
 
+  # AmbiguousError - raise this error when a search
+  # term that should find one object finds more.
+  #
+  class AmbiguousError < RuntimeError; end
+
   # FileServiceError - raise this error when
   # there's a problem accessing file service on a
   # distribution point.
@@ -73,7 +77,7 @@ module Jamf
   class UnsupportedError < RuntimeError; end
 
   # TimeoutError - raise this when we
-  # try to do something and it times out
+  # try to do and it times out
   #
   class TimeoutError < RuntimeError; end
 
@@ -82,27 +86,22 @@ module Jamf
   #
   class AuthenticationError < RuntimeError; end
 
-  # InvalidTokenError - raise this when a connection token is
-  # expired or otherwise invalid
+  # Authorization error - rause this when the
+  # user doesn't have permission to do something
   #
-  class InvalidTokenError < RuntimeError; end
+  class AuthorizationError < RuntimeError ; end
 
   # ConflictError - raise this when
   # attempts to PUT or PUSH to the API
   # result in a 409 Conflict http error.
-  # See {Jamf::APIConnection#raise_conflict_error}
+  # See {Jamf::Connection#raise_conflict_error}
   #
   class ConflictError < RuntimeError; end
 
-  # A 409 error specifically raised when a Lockable resource
-  # has changed between fetching and saving.
-  # See the Jamf::Lockable mixin.
-  class VersionLockError < ConflictError; end
-
   # BadRequestError - raise this when
   # attempts to PUT or PUSH or DELETE to the API
   # result in a 400 Bad Request http error.
-  # See {Jamf::APIConnection.raise_bad_request_error}
+  # See {Jamf::Connection.raise_bad_request_error}
   #
   class BadRequestError < RuntimeError; end
 
@@ -110,8 +109,8 @@ module Jamf
   # attempts API actions generate an error not dealt with
   # by ConflictError or BadRequestError
   # result in a 400 Bad Request http error.
-  # See {Jamf::APIConnection.raise_api_error}
+  # See {Jamf::Connection.raise_api_error}
   #
   class APIRequestError < RuntimeError; end
 
-end # module JAMF
+end # module Jamf