stormpath-sdk 0.2.0 → 0.3.0

data/CHANGES.md

@@ -0,0 +1,31 @@
+stormpath-sdk-ruby Changelog
+====================
+
+Version 0.3.0
+-------------
+
+Released on August 31, 2012
+
+- The properties method is now protected, only available for the resources hierarchy. The properties on the data store are now obtained via Stormpath::Resource::Resource's get_property_names and get_property functions.
+- The 'inspect' and 'to_s' methods were overridden in Stormpath::Resource::Resource to keep some properties (like password) from being displayed.
+- Logic to retain non-persisted properties was added (dirty properties).
+- A resource's property can now be removed by setting it to nil.
+- The Stormpath::Client::ClientApplicationBuilder class was added and implemented to produce a Stormpath::Client::ClientApplication from a single URL with the credentials on it.
+
+
+Version 0.2.0
+-------------
+
+Released on August 20, 2012
+
+- Result of the Application authentication was changed from Account to AuthenticationResult.
+- The password verification's method name for token creation on the Application class was changed to 'send_password_reset_email'.
+- The 'verify_password_reset_token' method on the Application class now returns an Account instead of a PasswordResetToken.
+- The API RDOC was updated for the previously modified implementations on the Application class.
+
+Version 0.1.0
+-------------
+
+Released on July 27, 2012
+
+- First release of the Stormpath Ruby SDK where all of the features available on the REST API by the release date were implemented.

data/README.md

@@ -13,7 +13,10 @@ https://github.com/stormpath/stormpath-sdk-ruby/wiki
 
 Via rubygems.org:
 
+```
 $ gem install stormpath-sdk
+```
+
 To build and install the development branch yourself from the latest source:
 
 ```

data/lib/stormpath-sdk.rb

@@ -13,6 +13,8 @@ require "stormpath-sdk/client/api_key"
 require "stormpath-sdk/client/client"
 require "stormpath-sdk/util/hash"
 require "stormpath-sdk/client/client_builder"
+require "stormpath-sdk/client/client_application"
+require "stormpath-sdk/client/client_application_builder"
 require "stormpath-sdk/auth/username_password_request"
 require "stormpath-sdk/resource/status"
 require "stormpath-sdk/resource/utils"

data/lib/stormpath-sdk/auth/username_password_request.rb

@@ -21,7 +21,7 @@ module Stormpath
 
       attr_reader :host
 
-      def initialize username, password, host
+      def initialize username, password, host = nil
         @username = username
         @password = (password != nil and password.length > 0) ? password.chars.to_a : "".chars.to_a
         @host = host

data/lib/stormpath-sdk/client/client_application.rb

@@ -0,0 +1,38 @@
+#
+# Copyright 2012 Stormpath, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+module Stormpath
+
+  module Client
+
+    # A ClientApplication is a simple wrapper around a {@link Stormpath::Client::Client} and
+    # {@link Stormpath::Resource::Application} instance, returned from
+    # the {@code ClientApplicationBuilder}.{@link Stormpath::Client::ClientApplicationBuilder#build_application}
+    # method.
+    # @since 0.3.0
+    class ClientApplication
+
+      attr_reader :client, :application
+
+      def initialize client, application
+        @client = client
+        @application = application
+      end
+
+    end
+
+  end
+
+end

data/lib/stormpath-sdk/client/client_application_builder.rb

@@ -0,0 +1,351 @@
+#
+# Copyright 2012 Stormpath, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+module Stormpath
+
+  module Client
+
+    ##
+    # A <a href="http://en.wikipedia.org/wiki/Builder_pattern">Builder design pattern</a> implementation similar to
+    # the {@link Stormpath::Client::ClientBuilder}, but focused on single-application interaction with Stormpath.
+    # <h2>Description</h2>
+    # The {@code ClientBuilder} produces a {@link Stormpath::Client::Client} instance useful for interacting with any aspect
+    # of an entire Stormpath Tenant's data space.  However, a software application may only be interested in its own
+    # functionality and not the entire Stormpath Tenant data space.
+    # <p/>
+    # The {@code ClientApplicationBuilder} provides a means to more easily acquiring a single
+    # {@link Stormpath::Resource::Application} instance.  From this {@code Application} instance, everything a particular
+    # Application needs to perform can be based off of this instance and the wider-scoped concerns of an entire Tenant can be ignored.
+    # <h2>Default Usage</h2>
+    # <pre>
+    # # this can be a file disk or url location as well:
+    # location = "/home/jsmith/.stormpath/apiKey.yml"
+    #
+    # app_href = "https://api.stormpath.com/v1/applications/YOUR_APP_UID_HERE"
+    #
+    # application = new ClientApplicationBuilder.new.
+    #               set_api_key_file_location(location).
+    #            <b>set_application_href(app_href)</b>.
+    #               build.
+    #               application
+    # </pre>
+    # <p/>
+    # After acquiring the {@code Application} instance, you can interact with it to login accounts, reset passwords,
+    # etc.
+    # <h2>Service Provider Usage with only an Application URL</h2>
+    # Some hosting service providers (e.g. like <a href="http://www.heroku.com">Heroku</a>) do not allow easy access to
+    # a configuration file and therefore it might be difficult to reference an API Key File.  If you cannot reference an
+    # API Key File via the {@code YAML file} or {@code YAML object} or {@code url}
+    # {@link ClientBuilder#set_api_key_file_location(String) resource locations}, the Application HREF URL must contain the
+    # API Key embedded as the <em><a href="http://en.wikipedia.org/wiki/URI_scheme">user info</a></em> portion of the
+    # URL.  For example:
+    # <p/>
+    # <pre>
+    # https://<b>apiKeyId:apiKeySecret@</b>api.stormpath.com/v1/applications/YOUR_APP_UID_HERE
+    # </pre>
+    # <p/>
+    # Notice this is just a normal Application HREF url with the <b>apiKeyId:apiKeySecret@</b> part added in.
+    # <p/>
+    # Example usage:
+    # <pre>
+    # appHref = "https://<b>apiKeyId:apiKeySecret@</b>api.stormpath.com/v1/applications/YOUR_APP_UID_HERE";
+    #
+    # application = new ClientApplicationBuilder.new.
+    #            <b>set_application_href(appHref)</b>.
+    #               build.
+    #               application
+    # </pre>
+    # <p/>
+    # <b>WARNING: ONLY use the embedded API Key technique if you do not have access to {@code YAML file} or
+    # {@code YAML object} or {@code url} {@link ClientApplicationBuilder#set_api_key_file_location(String) resource locations}</b>.
+    # File based API Key storage is a more secure technique than embedding the key in the URL itself.  Also, again,
+    # NEVER share your API Key Secret with <em>anyone</em> (not even co-workers).
+    # Stormpath staff will never ask for your API Key Secret.
+    #
+    # @see #set_api_key_file_location(String)
+    # @see #set_application_href(String)
+    # @since 0.3.0
+    #
+    class ClientApplicationBuilder
+
+      include Stormpath::Client
+      include Stormpath::Util::Assert
+
+      DOUBLE_SLASH = "//"
+
+      def initialize client_builder = ClientBuilder.new
+
+        assert_kind_of ClientBuilder, client_builder, 'client_builder must be kind of Stormpath::Client::ClientBuilder'
+        @client_builder = client_builder
+
+      end
+
+      # Allows usage of a YAML loadable object (IO object or the result of invoking Object.to_yaml)
+      # instead of loading a YAML file via {@link #set_api_key_file_location apiKeyFileLocation} configuration.
+      # <p/>
+      # The YAML contents and property name overrides function the same as described in the
+      # {@link #set_api_key_file_location setApiKeyFileLocation} RDoc.
+      #
+      # @param properties the YAML object to use to load the API Key ID and Secret.
+      # @return this ClientApplicationBuilder instance for method chaining.
+      def set_api_key_properties properties
+
+        @client_builder.set_api_key_properties properties
+        self
+
+      end
+
+      # Creates an API Key YAML object based on the specified File instead of loading a YAML
+      # file via  {@link #set_api_key_file_location apiKeyFileLocation} configuration. This file argument
+      # needs to be an IO instance.
+      # <p/>
+      # The constructed YAML contents and property name overrides function the same as described in the
+      # {@link #set_api_key_file_location setApiKeyFileLocation} RDoc.
+      # @param file the file to use to construct a YAML object.
+      # @return this ClientApplicationBuilder instance for method chaining.
+      def set_api_key_file file
+
+        @client_builder.set_api_key_file file
+        self
+
+      end
+
+      # Sets the location of the YAML file to load containing the API Key (Id and secret) used by the
+      # Client to communicate with the Stormpath REST API.
+      # <p/>
+      # You may load files from the filesystem, or URLs just specifying the file location.
+      # <h3>File Contents</h3>
+      # <p/>
+      # When the file is loaded, the following name/value pairs are expected to be present by default:
+      # <table>
+      #     <tr>
+      #         <th>Key</th>
+      #         <th>Value</th>
+      #     </tr>
+      #     <tr>
+      #         <td>apiKey.id</td>
+      #         <td>An individual account's API Key ID</td>
+      #     </tr>
+      #     <tr>
+      #         <td>apiKey.secret</td>
+      #         <td>The API Key Secret (password) that verifies the paired API Key ID.</td>
+      #     </tr>
+      # </table>
+      # <p/>
+      # Assuming you were using these default property names, your {@code ClientApplicationBuilder} usage might look like the
+      # following:
+      # <pre>
+      # location = "/home/jsmith/.stormpath/apiKey.yml";
+      #
+      # application_href = 'https://<b>apiKeyId:apiKeySecret@</b>api.stormpath.com/v1/applications/YOUR_APP_UID_HERE'
+      #
+      # application = ClientApplicationBuilder.new.
+      #               set_application_href(application_href).
+      #               set_api_key_file_location(location).
+      #               build.
+      #               application
+      # </pre>
+      # <h3>Custom Property Names</h3>
+      # If you want to control the property names used in the file, you may configure them via
+      # {@link #set_api_key_id_property_name(String) set_api_key_id_property_name} and
+      # {@link #set_api_key_secret_property_name(String) set_api_key_secret_property_name}.
+      # <p/>
+      # For example, if you had a {@code /home/jsmith/.stormpath/apiKey.yml} file with the following
+      # name/value pairs:
+      # <pre>
+      # myStormpathApiKeyId = 'foo'
+      # myStormpathApiKeySecret = 'mySuperSecretValue'
+      # </pre>
+      # Your {@code ClientApplicationBuilder} usage would look like the following:
+      # <pre>
+      # location = "/home/jsmith/.stormpath/apiKey.yml";
+      #
+      # application = ClientApplicationBuilder.new.
+      #               set_api_key_file_location(location).
+      #               set_api_key_id_property_name("myStormpathApiKeyId").
+      #               set_api_key_secret_property_name("myStormpathApiKeySecret").
+      #               set_application_href(application_href).
+      #               build.
+      #               application
+      # </pre>
+      #
+      # @param location the file or url location of the API Key {@code .yml} file to load when
+      #                 constructing the API Key to use for communicating with the Stormpath REST API.
+      #
+      # @return this ClientApplicationBuilder instance for method chaining.
+      #/
+      def set_api_key_file_location location
+
+        @client_builder.set_api_key_file_location location
+        self
+
+      end
+
+      # Sets the name used to query for the API Key ID from a YAML instance.  That is:
+      # <pre>
+      # apiKeyId = yml.access(<b>api_key_id_property_name</b>)
+      # </pre>
+      #
+      # The Hash#access method searches through the provided path and returns the found value.
+      #
+      # The <b>api_key_id_property_name</b> key can be as deep as needed, as long as it comes
+      # in the exact path order.
+      # Example: Having the file 'apiKey.yml' with the following content:
+      #
+      #           stormpath:
+      #             apiKey:
+      #             id: myStormpathApiKeyId
+      #
+      # The method should be called as follows:
+      #
+      #           ClientApplicationBuilder#set_api_key_id_property_name('stormpath', 'apiKey', 'id')
+      #
+      # @param api_key_id_property_name the name used to query for the API Key ID from a YAML instance.
+      # @return this ClientApplicationBuilder instance for method chaining.
+      def set_api_key_id_property_name *api_key_id_property_name
+
+        @client_builder.set_api_key_id_property_name *api_key_id_property_name
+        self
+
+      end
+
+      # Sets the name used to query for the API Key Secret from a YAML instance.  That is:
+      # <pre>
+      # apiKeyId = yml.access(<b>api_key_secret_property_name</b>)
+      # </pre>
+      #
+      # The Hash#access method searches through the provided path and returns the found value.
+      #
+      # The <b>api_key_secret_property_name</b> key can be as deep as needed, as long as it comes
+      # in the exact path order.
+      # Example: Having the file 'apiKey.yml' with the following content:
+      #
+      #           stormpath:
+      #             apiKey:
+      #             secret: myStormpathApiKeyId
+      #
+      # The method should be called as follows:
+      #
+      #           ClientApplicationBuilder#set_api_key_id_property_name('stormpath', 'apiKey', 'secret')
+      #
+      # @param api_key_secret_property_name the name used to query for the API Key Secret from a YAML instance.
+      # @return this ClientApplicationBuilder instance for method chaining.
+      def set_api_key_secret_property_name *api_key_secret_property_name
+
+        @client_builder.set_api_key_secret_property_name *api_key_secret_property_name
+        self
+
+      end
+
+      ##
+      # Sets the fully qualified Stormpath Application HREF (a URL) to use to acquire the Application instance when
+      # {@link #build_application} is called.  See the Class-level RDoc for usage scenarios.
+      #
+      # @param applicationHref the fully qualified Stormpath Application HREF (a URL) to use to acquire the
+      #                        Application instance when {@link #build_application} is called.
+      # @return this ClientApplicationBuilder instance for method chaining.
+      def set_application_href application_href
+
+        @application_href = application_href
+        self
+
+      end
+
+      # Builds a Client and Application wrapper instance based on the configured
+      # {@link #set_application_href}. See the Class-level RDoc for usage scenarios.
+      #
+      # @return a Client and Application wrapper instance based on the configured {@link #set_application_href}.
+      def build
+
+        href = !@application_href.nil? ? @application_href.strip : nil
+
+        assert_false (href.nil? or href.empty?),
+                     "'application_href' property must be specified when using this builder implementation."
+
+
+        cleaned_href = href
+
+        at_sigh_index = href.index '@'
+
+        if !at_sigh_index.nil?
+
+          parts = get_href_with_user_info href, at_sigh_index
+
+          cleaned_href = parts[0] + parts[2]
+
+          parts = parts[1].split ':', 2
+
+          api_key_properties = create_api_key_properties parts
+
+          set_api_key_properties api_key_properties
+
+        end #otherwise an apiKey File/YAML/etc for the API Key is required
+
+        client = build_client
+
+        application = client.data_store.get_resource cleaned_href, Application
+
+        ClientApplication.new client, application
+
+      end
+
+      protected
+
+      def build_client
+        @client_builder.build
+      end
+
+      def get_href_with_user_info href, at_sign_index
+
+        assert_kind_of String, href, 'href must be kind of String'
+        assert_kind_of Fixnum, at_sign_index, 'at_sign_index must be kind of Fixnum'
+
+        double_slash_index = href.index DOUBLE_SLASH
+
+        assert_not_nil double_slash_index, 'Invalid application href URL'
+
+        parts = Array.new 3
+
+        parts[0] = href[0..double_slash_index + 1] #up to and including the double slash
+        parts[1] = href[double_slash_index + DOUBLE_SLASH.length..at_sign_index -1] #raw user info
+        parts[2] = href[at_sign_index + 1..href.length - 1] #after the @ character
+
+        parts
+
+      end
+
+      def create_api_key_properties pair
+
+        assert_kind_of Array, pair, 'pair must be kind of Array'
+
+        assert_true (pair.length == 2), 'application_href userInfo segment must consist' +
+            ' of the following format: apiKeyId:apiKeySecret'
+
+        properties = Hash.new
+        properties.store 'apiKey.id', url_decode(pair[0])
+        properties.store 'apiKey.secret', url_decode(pair[1])
+
+        properties.to_yaml
+
+      end
+
+      def url_decode url
+        URI.decode url
+      end
+    end
+
+  end
+
+end

data/lib/stormpath-sdk/client/client_builder.rb

@@ -28,7 +28,7 @@ module Stormpath
     # <pre>
     # location = "/home/jsmith/.stormpath/apiKey.yml";
     #
-    # client = ClientBuilder.new.set_api_key_file_location(location).build()
+    # client = ClientBuilder.new.set_api_key_file_location(location).build
     # </pre>
     # <p/>
     # You may load files from the filesystem or URLs by specifying the file location.
@@ -102,14 +102,14 @@ module Stormpath
       # <pre>
       # location = "/home/jsmith/.stormpath/apiKey.yml";
       #
-      # client = ClientBuilder.new.set_api_key_file_location(location).build()
+      # client = ClientBuilder.new.set_api_key_file_location(location).build
       # </pre>
       # <h3>Custom Property Names</h3>
       # If you want to control the property names used in the file, you may configure them via
       # {@link #set_api_key_id_property_name(String) set_api_key_id_property_name} and
       # {@link #set_api_key_secret_property_name(String) set_api_key_secret_property_name}.
       # <p/>
-      # For example, if you had a {@code /home/jsmith/.stormpath/apiKey.properties} file with the following
+      # For example, if you had a {@code /home/jsmith/.stormpath/apiKey.yml} file with the following
       # name/value pairs:
       # <pre>
       # myStormpathApiKeyId = 'foo'
@@ -133,9 +133,11 @@ module Stormpath
       # @return the ClientBuilder instance for method chaining.
       #/
       def set_api_key_file_location location
+
         assert_kind_of String, location, 'location must be kind of String'
         @api_key_file_location = location
         self
+
       end
 
 
@@ -209,11 +211,9 @@ module Stormpath
 
           file = get_available_file
 
-          if file.nil?
-            raise ArgumentError, "No API Key file could be found or loaded from a file location.  Please " +
-                "configure the 'apiKeyFileLocation' property or alternatively configure a " +
-                "YAML loadable instance."
-          end
+          assert_not_nil file, "No API Key file could be found or loaded from a file location.  Please " +
+              "configure the 'apiKeyFileLocation' property or alternatively configure a " +
+              "YAML loadable instance."
 
           yaml_obj = YAML::load(file)
 
@@ -237,8 +237,10 @@ module Stormpath
       end
 
       def set_base_url base_url
+
         @base_url = base_url
         self
+
       end
 
       private
@@ -277,13 +279,10 @@ module Stormpath
             prop_name_value,
                                    separator)
 
-        if value.nil?
-
-          raise ArgumentError, "There is no '" + prop_name.join(':') + "' property in the " +
-              "configured apiKey YAML.  You can either specify that property or " +
-              "configure the " + masterName + "PropertyName value on the ClientBuilder to specify a " +
-              "custom property name."
-        end
+        assert_not_nil value, "There is no '" + prop_name.join(':') + "' property in the " +
+            "configured apiKey YAML.  You can either specify that property or " +
+            "configure the #{masterName}_property_name value on the ClientBuilder to specify a " +
+            "custom property name."
 
         value
 

data/lib/stormpath-sdk/ds/data_store.rb

@@ -36,7 +36,7 @@ module Stormpath
         @resource_factory = ResourceFactory.new(self)
       end
 
-      def instantiate(clazz, properties)
+      def instantiate(clazz, properties = {})
 
         @resource_factory.instantiate(clazz, properties)
       end
@@ -60,7 +60,7 @@ module Stormpath
 
         if resource.kind_of? return_type
 
-          resource.set_properties returned_resource.properties
+          resource.set_properties to_hash(returned_resource)
 
         end
 
@@ -84,7 +84,7 @@ module Stormpath
         return_value = save_resource href, resource, clazz
 
         #ensure the caller's argument is updated with what is returned from the server:
-        resource.set_properties return_value.properties
+        resource.set_properties to_hash(return_value)
 
         return_value
 
@@ -156,7 +156,7 @@ module Stormpath
           q_href = qualify q_href
         end
 
-        response = execute_request('post', q_href, MultiJson.dump(resource.properties))
+        response = execute_request('post', q_href, MultiJson.dump(to_hash(resource)))
         @resource_factory.instantiate(return_type, response.to_hash)
 
       end
@@ -167,6 +167,41 @@ module Stormpath
             "https://" + DEFAULT_SERVER_HOST + "/v" + DEFAULT_API_VERSION.to_s
       end
 
+      def to_hash resource
+
+        property_names = resource.get_property_names
+        properties = Hash.new
+
+        property_names.each do |name|
+
+          property = resource.get_property name
+
+          if property.kind_of? Hash
+
+            property = to_simple_reference name, property
+
+          end
+
+          properties.store name, property
+
+        end
+
+        properties
+
+      end
+
+      def to_simple_reference property_name, hash
+
+        href_prop_name = Resource::Resource::HREF_PROP_NAME
+        assert_true (hash.kind_of? Hash and !hash.empty? and hash.has_key? href_prop_name), "Nested resource " +
+            "'#{property_name}' must have an 'href' property."
+
+        href = hash[href_prop_name]
+
+        {href_prop_name => href}
+
+      end
+
     end
 
   end

data/lib/stormpath-sdk/ds/resource_factory.rb

@@ -24,7 +24,7 @@ module Stormpath
         @data_store = data_store
       end
 
-      def instantiate(clazz, constructor_args)
+      def instantiate(clazz, constructor_args = {})
 
         clazz.new @data_store, constructor_args
       end

data/lib/stormpath-sdk/resource/account.rb

@@ -118,6 +118,11 @@ module Stormpath
         get_resource_property GROUP_MEMBERSHIPS, GroupMembershipList
       end
 
+      protected
+      def printable_property? property_name
+        PASSWORD != property_name
+      end
+
     end
 
   end

data/lib/stormpath-sdk/resource/resource.rb

@@ -23,12 +23,13 @@ module Stormpath
 
       HREF_PROP_NAME = "href"
 
-      def initialize data_store, properties
+      def initialize data_store, properties = {}
 
         @data_store = data_store
         @read_lock = Mutex.new
         @write_lock = Mutex.new
         @properties = Hash.new
+        @dirty_properties = Hash.new
         set_properties properties
 
       end
@@ -39,10 +40,15 @@ module Stormpath
 
         begin
 
+          @properties.clear
+          @dirty_properties.clear
           @dirty = false
 
           if !properties.nil? and properties.is_a? Hash
             @properties.replace properties
+
+            # Don't consider this resource materialized if it is only a reference.  A reference is any object that
+            # has only one 'href' property.
             href_only = @properties.size == 1 and @properties.has_key? HREF_PROP_NAME
             @materialized = !href_only
 
@@ -61,8 +67,28 @@ module Stormpath
           #not the href/id, must be a property that requires materialization:
           if !is_new and !materialized
 
-            materialize
+            # only materialize if the property hasn't been set previously (no need to execute a server
+            # request since we have the most recent value already):
+            present = false
+            @read_lock.lock
+
+            begin
+
+              present = @dirty_properties.has_key? name
+
+            ensure
+
+              @read_lock.unlock
+
+            end
+
+            if !present
+              # exhausted present properties - we require a server call:
+              materialize
+            end
+
           end
+
         end
 
         read_property name
@@ -83,7 +109,105 @@ module Stormpath
         get_property HREF_PROP_NAME
       end
 
-      attr_reader :properties
+      def inspect
+
+        @read_lock.lock
+
+        str = ''
+
+        begin
+
+          counter = 2
+          @properties.each do |key, value|
+
+            if str.empty?
+
+              str = '#<' + class_name_with_id + ' @properties={'
+
+            else
+
+              if printable_property? key
+
+                str << "\"#{key}\"=>"
+
+                if value.kind_of? Hash and value.has_key? HREF_PROP_NAME
+
+                  str << '{"' << HREF_PROP_NAME + '"=>"' + value[HREF_PROP_NAME] + '"}'
+
+                else
+
+                  str << "\"#{value}\""
+
+                end
+
+                if counter < @properties.length
+
+                  str << ', '
+
+                end
+
+              end
+
+              counter+= 1
+
+            end
+
+          end
+
+        ensure
+
+          @read_lock.unlock
+
+        end
+
+        if !str.empty?
+          str << '}>'
+        end
+
+        str
+
+      end
+
+      def to_s
+        '#<' + class_name_with_id + '>'
+      end
+
+      def to_yaml
+
+        yaml = '--- !ruby/object:' << self.class.name << "\n"
+
+        @read_lock.lock
+
+        begin
+
+          first_property = true
+          @properties.each do |key, value|
+
+            if printable_property? key
+
+              if first_property
+
+                yaml << " properties\n "
+
+              end
+
+              yaml << ' ' << key << ': ' << value << "\n"
+
+              first_property = false
+
+            end
+
+          end
+
+        ensure
+
+          @read_lock.unlock
+
+        end
+
+        yaml << "\n"
+
+      end
 
       protected
 
@@ -126,18 +250,9 @@ module Stormpath
         @write_lock.lock
 
         begin
-          if value.nil?
-
-            removed = @properties.delete name
-
-            if !removed.nil?
-              @dirty = true
-            end
-
-          else
-            @properties.store name, value
-            @dirty = true
-          end
+          @properties.store name, value
+          @dirty_properties.store name, value
+          @dirty = true
         ensure
           @write_lock.unlock
         end
@@ -153,12 +268,32 @@ module Stormpath
 
           resource = @data_store.get_resource get_href, clazz
           @properties.replace resource.properties
+
+          #retain dirty properties:
+          @properties.merge! @dirty_properties
+
           @materialized = true
 
         ensure
 
           @write_lock.unlock
         end
+
+      end
+
+      def properties
+        @properties
+      end
+
+      ##
+      # Returns {@code true} if the internal property is safe to print in to_s or inspect, {@code false} otherwise.
+      #
+      # @param property_name The name of the property to check for safe printing
+      # @return {@code true} if the internal property is safe to print in to_s, {@code false} otherwise.
+      def printable_property? property_name
+
+        return true
+
       end
 
       private
@@ -182,6 +317,10 @@ module Stormpath
         end
 
       end
+
+      def class_name_with_id
+        self.class.name + ':0x' + ('%x' % (self.object_id << 1)).to_s
+      end
     end
   end
 

data/lib/stormpath-sdk/util/assert.rb

@@ -36,6 +36,13 @@ module Stormpath
         raise ArgumentError, message, caller unless arg
 
       end
+
+      def assert_false arg, message
+
+        raise ArgumentError, message, caller unless !arg
+
+      end
+
     end
   end
 end

data/lib/stormpath-sdk/version.rb

@@ -14,6 +14,6 @@
 # limitations under the License.
 #
 module Stormpath
-  VERSION = '0.2.0'
-  VERSION_DATE = '2012-08-20'
+  VERSION = '0.3.0'
+  VERSION_DATE = '2012-08-31'
 end

data/test/client/client_application_builder_spec.rb

@@ -0,0 +1,114 @@
+require "stormpath-sdk"
+
+include Stormpath::Client
+
+describe "Client Application Builder Tests" do
+
+  before(:all) do
+    @client_file = 'test/client/client.yml'
+    @client_remote_file = 'http://localhost:8081/client.yml'
+    @application_href = 'http://localhost:8080/v1/applications/A0atUpZARYGApaN5f88O3A'
+    @http_prefix = 'http://'
+    @app_href_without_http = '@localhost:8080/v1/applications/A0atUpZARYGApaN5f88O3A'
+    @client_builder = ClientBuilder.new.set_base_url 'http://localhost:8080/v1'
+    @test_remote_file = false
+  end
+
+
+  it 'Builder should read default properties from YAML file location with application href' do
+
+    result = ClientApplicationBuilder.new(@client_builder).
+        set_api_key_file_location(@client_file).
+        set_application_href(@application_href).
+        build
+
+    result.should be_kind_of ClientApplication
+
+  end
+
+  it 'Builder should create ClientApplication with data from application href with credentials' do
+
+    # getting the properties from file...just to avoid writing them directly
+    # in the 'properties' Hash
+    yml_obj = YAML::load(File.open @client_file)
+    api_key_id_keyword = 'apiKey.id'
+    api_key_secret_keyword = 'apiKey.secret'
+
+    # we create the client from this Hash instead of from a file
+    properties = {api_key_id_keyword => yml_obj[api_key_id_keyword],
+                  api_key_secret_keyword => yml_obj[api_key_secret_keyword]}
+
+    application_href = @http_prefix +
+        properties[api_key_id_keyword] +
+        ':' +
+        properties[api_key_secret_keyword] +
+        @app_href_without_http
+
+    result = ClientApplicationBuilder.new(@client_builder).
+        set_application_href(application_href).
+        build
+
+    result.should be_kind_of ClientApplication
+
+  end
+
+  it 'Builder should read custom complex properties from YAML file locatio with application href' do
+
+    @client_builder = ClientBuilder.new.set_base_url 'http://localhost:8080/v1'
+    result = ClientApplicationBuilder.new(@client_builder).
+        set_api_key_file_location(@client_file).
+        set_api_key_id_property_name('stormpath', 'apiKey', 'id').
+        set_api_key_secret_property_name('stormpath', 'apiKey', 'secret').
+        set_application_href(@application_href).
+        build
+
+    result.should be_kind_of ClientApplication
+
+  end
+
+  it 'Builder should read custom simple properties from YAML file locatio with application href' do
+
+    # getting the properties from file...just to avoid writing them directly
+    # in the 'properties' Hash
+    yml_obj = YAML::load(File.open @client_file)
+    api_key_id_keyword = 'different.apiKey.id'
+    api_key_secret_keyword = 'different.apiKey.secret'
+
+    # we create the client from this Hash instead of from a file
+    properties = {api_key_id_keyword => yml_obj[api_key_id_keyword],
+                  api_key_secret_keyword => yml_obj[api_key_secret_keyword]}
+
+    result = ClientApplicationBuilder.new(@client_builder).
+        set_api_key_properties(properties.to_yaml).
+        set_api_key_id_property_name(api_key_id_keyword).
+        set_api_key_secret_property_name(api_key_secret_keyword).
+        set_application_href(@application_href).
+        build
+
+    result.should be_kind_of ClientApplication
+
+  end
+
+  it 'Builder should throw exception when creating it with wrong argument' do
+
+    expect { ClientApplicationBuilder.new 'WRONG' }.to raise_error ArgumentError
+
+  end
+
+  it 'Builder should throw exception when trying to build without application href' do
+
+    expect { ClientApplicationBuilder.new(@client_builder).build }.to raise_error ArgumentError
+
+  end
+
+  it 'Builder should throw exception when trying to build with an invalid application href' do
+
+    expect { ClientApplicationBuilder.new(@client_builder).
+        set_api_key_file_location(@client_file).
+        set_application_href('id:secret@stormpath.com/v1').
+        build }.
+        to raise_error ArgumentError
+
+  end
+
+end

data/test/client/read_spec.rb

@@ -237,6 +237,19 @@ describe "READ Operations" do
 
   end
 
+  it "dirty properties must be retained after materialization" do
+
+    account = @data_store.instantiate Account, {'href' => 'accounts/gJH4bh6QQKK0awRmwD72Cg'}
+
+    name = 'Name Before Materialization'
+
+    account.set_given_name name
+
+    account.get_surname.should be_kind_of String
+
+    account.get_given_name.should == name
+  end
+
 end
 
 

data/test/client/write_spec.rb

@@ -10,10 +10,12 @@ describe "WRITE Operations" do
     @data_store = @client.data_store
     @create_account = false
     @update_account = false
+    @remove_account_property = false
     @update_application = false
     @update_directory = false
     @update_group = false
     @create_application = false
+    @change_password = false
     @verify_email = false
     @send_password_reset_email = false
     @verify_password_reset_token = false
@@ -25,10 +27,10 @@ describe "WRITE Operations" do
 
   it "application should be able to authenticate" do
 
-    href = 'applications/fzyWJ5V_SDORGPk4fT2jhA'
+    href = 'applications/A0atUpZARYGApaN5f88O3A'
     application = @data_store.get_resource href, Application
 
-    result = application.authenticate_account UsernamePasswordRequest.new 'tootertest', 'super_P4ss', nil
+    result = application.authenticate_account UsernamePasswordRequest.new 'kentucky', 'super_P4ss'
 
     result.should be_kind_of AuthenticationResult
 
@@ -39,9 +41,9 @@ describe "WRITE Operations" do
 
     begin
 
-      href = 'applications/fzyWJ5V_SDORGPk4fT2jhA'
+      href = 'applications/A0atUpZARYGApaN5f88O3A'
       application = @data_store.get_resource href, Application
-      result = application.authenticate_account UsernamePasswordRequest.new 'tootertest', 'WRONG_PASS', nil
+      result = application.authenticate_account UsernamePasswordRequest.new 'kentucky', 'WRONG_PASS'
 
     rescue ResourceError => re
       p '** Authentication Error **'
@@ -59,17 +61,17 @@ describe "WRITE Operations" do
 
     if (@create_account)
 
-      href = 'directories/wDTY5jppTLS2uZEAcqaL5A'
+      href = 'directories/_oIg8zU5QWyiz22DcVYVLg'
       directory = @data_store.get_resource href, Directory
 
-      account = @data_store.instantiate Account, nil
+      account = @data_store.instantiate Account
       account.set_email 'rubysdk@email.com'
       account.set_given_name 'Ruby'
       account.set_password 'super_P4ss'
       account.set_surname 'Sdk'
       account.set_username 'rubysdk'
 
-      result = directory.create_account account
+      result = directory.create_account account, false
 
       result.should be_kind_of Account
 
@@ -96,6 +98,30 @@ describe "WRITE Operations" do
 
   end
 
+  it "account property should be updated/removed" do
+
+    if (@remove_account_property)
+
+      href = 'accounts/gJH4bh6QQKK0awRmwD72Cg'
+      account = @data_store.get_resource href, Account
+
+      mod_value = 'Modified at: ' + Time.now.to_s
+      account.set_middle_name mod_value
+
+      account.save
+
+      account.get_middle_name.should == mod_value
+
+      account.set_middle_name nil
+
+      account.save
+
+      account.get_middle_name.should == nil
+
+    end
+
+  end
+
   it "application should be updated" do
 
     if (@update_application)
@@ -156,7 +182,7 @@ describe "WRITE Operations" do
 
       tenant = @client.current_tenant
 
-      application = @data_store.instantiate Application, nil
+      application = @data_store.instantiate Application
       application.set_name 'Test Application Creation'
       application.set_description 'Test Application Description'
 
@@ -214,6 +240,35 @@ describe "WRITE Operations" do
 
   end
 
+  it "password should be changed" do
+
+    if (@change_password)
+
+      href = 'applications/fzyWJ5V_SDORGPk4fT2jhA'
+      application = @data_store.get_resource href, Application
+
+      account = application.verify_password_reset_token 'TFMWt3lbQdWc7MNF48pJbw'
+
+      account.should be_kind_of Account
+
+      new_password = 'changed_P4ss'
+      account.set_password new_password
+      account.save
+
+      begin
+
+        application.authenticate_account UsernamePasswordRequest.new account.get_username, new_password
+
+      rescue ResourceError => re
+
+        false.should be true
+
+      end
+
+    end
+
+  end
+
   it "account should be created linked to a group" do
 
     if (@create_account_with_group_membership)
@@ -224,7 +279,7 @@ describe "WRITE Operations" do
       group_href = 'groups/mCidbrAcSF-VpkNfOVvJkQ'
       group = @data_store.get_resource group_href, Group
 
-      account = @data_store.instantiate Account, nil
+      account = @data_store.instantiate Account
       account.set_email 'rubysdkwithgroup@email.com'
       account.set_given_name 'Ruby'
       account.set_password 'super_P4ss'

data/test/resource/resource_spec.rb

@@ -0,0 +1,41 @@
+require "test/resource/test_resource"
+
+describe "Resource Tests" do
+
+  it "non materialized resource get dirty property without materializing" do
+
+    props = {'href' => 'http://foo.com/test/123'}
+    data_store = Stormpath::DataStore::DataStore.new '', ''
+
+    test_resource = TestResource.new data_store, props
+    name = 'New Name'
+    test_resource.set_name name
+
+    begin
+
+      name.should == test_resource.get_name
+
+    rescue Exception => e
+
+      true.should be false
+
+    end
+
+  end
+
+  it "password property must not show up on inspect" do
+
+    props = {'href' => 'http://foo.com/test/123'}
+    data_store = Stormpath::DataStore::DataStore.new '', ''
+
+    test_resource = TestResource.new data_store, props
+    name = 'New Name'
+    test_resource.set_name name
+
+    test_resource.set_password 'my_password'
+
+    test_resource.inspect.should_not include 'password'
+
+  end
+
+end

data/test/resource/test_resource.rb

@@ -0,0 +1,28 @@
+class TestResource < Stormpath::Resource::Resource
+
+  def get_name
+    get_property 'name'
+  end
+
+  def set_name name
+    set_property 'name', name
+  end
+
+  def get_description
+    get_property 'description'
+  end
+
+  def set_description description
+    set_property 'description', description
+  end
+
+  def set_password password
+    set_property 'password', password
+  end
+
+  protected
+  def printable_property? property_name
+    'password' != property_name
+  end
+
+end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 2
+  - 3
   - 0
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Elder Crisostomo
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-08-20 00:00:00 -07:00
+date: 2012-08-31 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -138,6 +138,8 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- .gitignore
+- CHANGES.md
 - Gemfile
 - README.md
 - Rakefile
@@ -148,6 +150,8 @@ files:
 - lib/stormpath-sdk/auth/username_password_request.rb
 - lib/stormpath-sdk/client/api_key.rb
 - lib/stormpath-sdk/client/client.rb
+- lib/stormpath-sdk/client/client_application.rb
+- lib/stormpath-sdk/client/client_application_builder.rb
 - lib/stormpath-sdk/client/client_builder.rb
 - lib/stormpath-sdk/ds/data_store.rb
 - lib/stormpath-sdk/ds/resource_factory.rb
@@ -181,9 +185,12 @@ files:
 - lib/stormpath-sdk/version.rb
 - stormpath-sdk.gemspec
 - test/client/client.yml
-- test/client/clientbuilder_spec.rb
+- test/client/client_application_builder_spec.rb
+- test/client/client_builder_spec.rb
 - test/client/read_spec.rb
 - test/client/write_spec.rb
+- test/resource/resource_spec.rb
+- test/resource/test_resource.rb
 has_rdoc: true
 homepage: https://github.com/stormpath/stormpath-sdk-ruby
 licenses: []
@@ -219,6 +226,9 @@ signing_key:
 specification_version: 3
 summary: Stormpath SDK
 test_files: 
-- test/client/clientbuilder_spec.rb
+- test/client/client_application_builder_spec.rb
+- test/client/client_builder_spec.rb
 - test/client/read_spec.rb
 - test/client/write_spec.rb
+- test/resource/resource_spec.rb
+- test/resource/test_resource.rb