lib/datacentred/model/project.rb in datacentred-0.1.1pre vs lib/datacentred/model/project.rb in datacentred-1.1.1

@@ -1,44 +1,103 @@
 module Datacentred
   module Model
-    class Project < OpenStruct
-      def initialize(params)
-        params.delete("links") if params
-        params["created_at"] = Time.parse params["created_at"]
-        params["updated_at"] = Time.parse params["updated_at"]
-        super(params)
-      end
+    # A project on your DataCentred account.
+    #
+    # Projects (also called "Cloud Projects" or "Tenants") are a way of grouping together users and resources.
+    #
+    # All projects created in your DataCented account are backed by a corresponding project in OpenStack's identity service (Keystone).
+    #
+    # @attr [String] id
+    # @attr [String] name
+    # @attr [Hash] quota_set
+    # @attr_reader [Time] created_at
+    # @attr_reader [Time] updated_at
+    class Project < Base
+      class << self
+        # Create a new project.
+        #
+        # @param [Hash] params Project attributes
+        # @raise [Errors::UnprocessableEntity] Raised if validations fail for the supplied attributes.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Project] New project.
+        def create(params)
+          new Request::Projects.create params
+        end
 
-      def self.all
-        Request::Projects.list.map{ |project| new(project) }
-      end
+        # List all available projects.
+        #
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [[Project]] A collection of all projects on this account.
+        def all
+          Request::Projects.list.map{|project| new project }
+        end
 
-      def self.find(id)
-        new Request::Projects.show(id)
-      end
+        # Find a project by unique ID.
+        #
+        # @param [String] id The unique identifier for this project.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @raise [Errors::NotFound] Raised if the project couldn't be found.
+        # @return [Project] The project, if it exists.
+        def find(id)
+          new Request::Projects.show id
+        end
 
-      def self.create(params)
-        new Request::Projects.create(params)
-      end
+        # Update a project by unique ID.
+        #
+        # @param [String] id The unique identifier for this project.
+        # @param [Hash] params Project attributes.
+        # @raise [Errors::UnprocessableEntity] Raised if validations fail for the supplied attributes.
+        # @raise [Errors::NotFound] Raised if the project could not be found.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Project] The updated project.
+        def update(id, params)
+          new Request::Projects.update id, params
+        end
 
-      def self.update(id, params)
-        new Request::Projects.update(id, params)
-      end
+        # Permanently remove the specified project.
+        #
+        # @param [String] id The unique identifier for this project.
+        # @raise [Errors::NotFound] Raised if the project couldn't be found.
+        # @raise [Errors::UnprocessableEntity] Raised if validations fail for the specified project.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Boolean] Confirms the user was destroyed.
+        def destroy(id)
+          Request::Projects.destroy id
+          true
+        end
 
-      def self.remove(id)
-        Request::Projects.destroy(id)
-      end
+        # List all users assigned to this project.
+        #
+        # @param [String] id The unique identifier for this project.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [[User]] A collection of the project's users.
+        def users(id)
+          Request::Projects.list_users(id).map{|user| new user }
+        end
 
-      def self.users(id)
-        Request::Projects.list_users(id).map{ |user| new(user) }
-      end
+        # Add a new user to this project, giving them access to it via OpenStack.
+        #
+        # @param [String] project_id The unique identifier for this project.
+        # @param [String] user_id The unique identifier for this user.
+        # @raise [Errors::NotFound] Raised if the project or user couldn't be found.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Boolean] Confirms the user was added (or is already present).
+        def add_user(project_id:, user_id:)
+          Request::Projects.add_user project_id, user_id
+          true
+        end
 
-      def self.add_user(project_id, user_id)
-        Request::Projects.add_user(project_id, user_id)
-      end
-
-      def self.remove_user(project_id, user_id)
-        Request::Projects.remove_user(project_id, user_id)
+        # Remove user from this project, revoking their access to it on OpenStack.
+        #
+        # @param [String] project_id The unique identifier for this project.
+        # @param [String] user_id The unique identifier for this user.
+        # @raise [Errors::NotFound] Raised if project or user couldn't be found.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Boolean] Confirms that user was removed (or is already absent).
+        def remove_user(project_id:, user_id:)
+          Request::Projects.remove_user project_id, user_id
+          true
+        end
       end
     end
   end
 end