uri_service 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5012df111508e186ecb439067488e70ec5e511e5
-  data.tar.gz: af2dbf25aec0882474d1a8909cc26fd81007b1b8
+  metadata.gz: e14cec0a40986cc0327fca1d58b15704fd25c2c6
+  data.tar.gz: 6fe6e37e9ab65ded6c9c15fdeefa06e1d38c2507
 SHA512:
-  metadata.gz: 8a9c898ce08c8f34a2ca4d23f088b24c9d735cd3ac2ecf1f565bb47584ca2e46a333d89b956da404f56b4f5d517c8ee3625b16a45b555e60ee0fc5edeea4f704
-  data.tar.gz: f6b423ecf9d89676b3661fd027ca5ba14bca37affffe3bb9e16415559d0de451b637554e7fc774b46339a4d108cb4d9b1f63f94690eeb93d7f080cf9fb2289ee
+  metadata.gz: f59f8f12ea92b925b3414bcb3c63106656fa3d6661081af07d613066d14d8a9dbe1ccbe6b0aeeff81391bcfc4f37fd3d9bfc54d20d3d5d55f0a668891da3810a
+  data.tar.gz: 3d890e422301dfbd32da4920661abad3a928e646d480d1be33439d35033cc0271317f7e79654e43aeaeeabc10caa515868647897ebbc8a32e8d8df3b7cb71311

data/README.md

@@ -2,6 +2,20 @@
 
 A database-backed and Solr-cached lookup/creation service for URIs.  Works with or without Rails.
 
+### Major Concepts:
+
+**External Term (UriService::TermType::EXTERNAL)**
+
+Used when caching a value/URI pair from an external controlled vocabulary within your UriService datastore.  Example: We want to add an entry for U.S. President Abraham Lincoln to our UriService datastore, so we'll create an external term that references his Library of Congress URI.
+
+**Local Term (UriService::TermType::LOCAL)**
+
+Used when defining locally-managed terms in the UriService datastore. Automatically creates a local URI for a new local term.  Example: We want to maintain a vocabulary for various departments within a university, and we want to create locally-managed URIs for these departments.
+
+**Temporary Term (UriService::TermType::TEMPORARY)**
+
+Used when you want to add a value to your UriService datastore, but have no authority information about the term and do not wish to create a local URI. Temporary term entries cannot store additional data fields, and no two temporary terms within the same vocabulary can have the same value. Basically, a termporary term is intended to identify an *exact string value* rather than identifiying an intellectual entity. Temporary terms should eventually be replaced by external or local terms later on when more information is known about the entity to which you are referring .  Example: We want to record information about the author of an old and mysterious letter by "John Smith."  We don't know which "John Smith," this refers to, so we'll create (or re-use) a temporary URI that's associated with the value "John Smith."  One day, when we figure out more about the letter and the author, we'll be able to update the record information and refer to an external term that has a globally-recognized URI, or we'll create a local URI if an external URI is unavailable.
+
 ### Usage:
 
 **Install uri_service:**
@@ -132,16 +146,14 @@ UriService.client.list_vocabularies(limit, start)
 
 Create a term in a vocabulary:
 ```ruby
-# Creates a term in the 'names' vocabulary, using the given value, uri and a couple of custom key-value pairs
+# Create an EXTERNAL term in the 'names' vocabulary, using an external URI
+UriService.client.create_term(UriService::TermType::EXTERNAL, {vocabulary_string_key: 'names', value: 'Lincoln, Abraham, 1809-1865', uri: 'http://id.loc.gov/authorities/names/n79006779', additional_fields: {'is_awesome' => true, 'best_president' => true, 'hat_type' => 'Stove Pipe'}})
 
-UriService.client.create_term('names', 'Lincoln, Abraham, 1809-1865', 'http://id.loc.gov/authorities/names/n79006779', {'is_awesome' => true, 'best_president' => true, 'hat_type' => 'Stove Pipe'})
-```
+# Create a LOCAL term in the 'departments' vocabulary (note: A URI is not passed in because LOCAL terms generate their own URIs)
+UriService.client.create_term(UriService::TermType::LOCAL, {vocabulary_string_key: 'departments', value: 'Chemistry', additional_fields: {'department_code' => 'CHEM'}})
 
-Create a LOCAL term in a vocabulary (when you don't have a URI for your term):
-```ruby
-# Creates a new LOCAL term in the 'names' vocabulary.  New URI is automatically generated.
-
-UriService.client.create_local_term('names', 'Baby, Newborn', {'is_baby' => true})
+# Create a LOCAL term in the 'departments' vocabulary (note: A URI is not passed in because TEMPORARY terms generate their own URIs, and additional_fields are not allowed)
+UriService.client.create_term(UriService::TermType::LOCAL, {vocabulary_string_key: 'names', value: 'Smith, John'})
 ```
 
 Searching by string query for a term in a vocabulary:
@@ -153,17 +165,37 @@ UriService.client.find_terms_by_query('names', 'batman')
 #     'uri' => 'http://id.loc.gov/authorities/names/n91059657',
 #     'value' => 'Batman, John, 1800-1839',
 #     'vocabulary_string_key' => 'names',
-#     'is_local' => false
+#     'type' => 'external'
 #   }
 #   {
 #     'uri' => 'http://id.loc.gov/authorities/names/n82259885',
 #     'value' => 'Batman, Stephen, -1584',
 #     'vocabulary_string_key' => 'names',
-#     'is_local' => false
+#     'type' => 'external'
 #   },
 # ]
 ```
 
+Alternate way to find terms without a text query:
+```ruby
+UriService.client.find_terms_where(
+  {
+    'vocabulary_string_key' => 'names',
+    'value' => 'Smith, John',
+    'type' => UriService::TermType::EXTERNAL
+  },
+  11
+)
+
+# Above method call returns an array of up to 11 terms, or an empty array if no terms are found
+```
+
+Finding a single term by URI:
+```ruby
+UriService.client.find_term_by_uri('http://id.example.com/123')
+# Returns a term hash or nil
+```
+
 Listing terms in a vocabulary:
 ```ruby
 limit = 10

data/lib/uri_service/client.rb

@@ -175,7 +175,7 @@ class UriService::Client
       return create_term_impl(type, vocabulary_string_key, value, uri, additional_fields)
     else
       # URI should not be present
-      raise UriService::InvalidOptsError, "A uri cannot supplied for term type: #{type}." unless uri.nil?
+      raise UriService::InvalidOptsError, "A uri cannot supplied for term type: #{type}" unless uri.nil?
       
       if type == UriService::TermType::TEMPORARY
         # No two TEMPORARY terms within the same vocabulary can have the same value, so we generate a unique URI from a hash of the (vocabulary_string_key + value) to ensure uniqueness.
@@ -512,6 +512,9 @@ class UriService::Client
   # - Returns an existing TEMPORARY term if a user attempts to
   #   create a new TEMPORARY term with an existing value/vocabulary combo.
   def create_term_impl(type, vocabulary_string_key, value, uri, additional_fields)
+    
+    raise UriService::InvalidTermTypeError, 'Invalid type: ' + type unless VALID_TYPES.include?(type)
+    
     self.handle_database_disconnect do
       
       if type == UriService::TermType::TEMPORARY

data/lib/uri_service/version.rb

@@ -1,6 +1,6 @@
 module UriService
   
-  VERSION = '0.3.0'
+  VERSION = '0.3.1'
   
   def self.version
     VERSION

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: uri_service
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Eric O'Hanlon
@@ -207,3 +207,4 @@ specification_version: 4
 summary: A service for registering local URIs and performing both local and remote
   URI lookups.
 test_files: []
+has_rdoc: