xcapclient 1.0 → 1.1

data/ERRORS.rdoc

@@ -14,7 +14,7 @@ The XCAPClient library includes custom Ruby exceptions. All these exceptions inh
     * WrongAUID
     * DocumentError
     * HTTPError
-    * HTTPAuthenticationError
+      * HTTPAuthenticationError
       * HTTPNoMatchingETag
       * HTTPConflictError
       * HTTPDocumentNotModified
@@ -22,6 +22,7 @@ The XCAPClient library includes custom Ruby exceptions. All these exceptions inh
       * HTTPWrongContentType
       * HTTPBadRequest
       * HTTPServerError
+      * HTTPNotImplemented
       * HTTPUnknownError
     * XMLParsingError
 
@@ -109,7 +110,12 @@ The server replied "400 Bad Request". The request was malformed.
 
 ==== HTTPServerError < HTTPError
 
-The server replied "500 Internal Server Error". The server encountered an unexpected condition which prevented it from fulfilling the request.
+The server replied "500 Internal Server Error" or "503 Service Unavailable". The server encountered an unexpected condition which prevented it from fulfilling the request.
+
+
+==== HTTPNotImplemented < HTTPError
+
+The server replied "501 Not Implemented". The server doesn't implement the request method.
 
 
 ==== HTTPUnknownError < HTTPError

data/README.rdoc

@@ -1,4 +1,4 @@
-= XCAPClient
+= XCAPClient (version 1.1.X)
 
 * http://dev.sipdoc.net/projects/ruby-xcapclient/wiki/
 * http://rubyforge.org/projects/xcapclient/
@@ -15,11 +15,11 @@ XCAPClient library implements the XCAP protocol in client side, allowing the app
 
 The library implements the following features:
 
-* Fetch, create/replace and delete a document.
-* Fetch, create/replace and delete a document element (XML node).
-* Fetch, create/replace and delete an element attribute.
+* Fetch, create/replace and delete a XML document.
+* Fetch, create/replace and delete a XML node.
+* Fetch, create/replace and delete a XML node attribute.
 * Full configurable parameters allowing customized fields for each XCAP application, such auid, XML namespace, MIME-Type, scope (:user or :global) and default document name ("index" if not set).
-* Fetch the namespaces and prefixes of a document node as they are used in the server.
+* Fetch the namespaces and prefixes of a document/node node as they are used in the server.
 * Manage of multiple documents per XCAP application.
 * Fetch the XCAP server auids, extensions and namespaces ("xcap-caps" application).
 * SSL.
@@ -115,20 +115,27 @@ By default, the methods accesing the XCAP server include the ETag if it's availa
   @xcapclient.put("pres-rules", "vacation-rules")
 
 
-==== Fetch an element
+==== Fetch a node (with "id" = "sip:alice@example.org")
 
-  @xcapclient.get_element("pres-rules", nil,
+  @xcapclient.get_node("pres-rules", nil,
     '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
     {"cp" => "urn:ietf:params:xml:ns:common-policy"})
   
 
-==== Add a new element (a new allowed user in "pres-rules" document)
+==== Add a new node (a new allowed user in "pres-rules" document)
 
-  @xcapclient.put_element("pres-rules", nil,
+  @xcapclient.put_node("pres-rules", nil,
     '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:bob@example.org"]',
     '<cp:one id="sip:bob@example.org"/>',
     {"cp"=>"urn:ietf:params:xml:ns:common-policy"})
 
+==== Fetch a node attribute (node "name" from node with "id" = "sip:alice@example.org")
+
+  @xcapclient.get_attribute("pres-rules", nil,
+    '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
+    "name",
+    {"cp" => "urn:ietf:params:xml:ns:common-policy"})
+
 
 == ToDo
 

data/lib/xcapclient/client.rb

@@ -40,7 +40,7 @@ module XCAPClient
 		USER_AGENT = "Ruby-XCAPClient"
 		COMMON_HEADERS = {
 			"User-Agent" => "#{USER_AGENT}/#{VERSION}",
-			"Connection" => "close"
+			"Connection" => "open"
 		}
 		GLOBAL_XUI = "global"
 		XCAP_CAPS_XMLNS = "urn:ietf:params:xml:ns:xcap-caps"
@@ -247,18 +247,18 @@ module XCAPClient
 		end
 		
 		
-		# Fetch an element from the document stored in the server.
+		# Fetch a node from the document stored in the server.
 		#
-		# Example:
+		# Example, fetching the node with "id" = "sip:alice@example.org":
 		#
-		#   @xcapclient.get_element("pres-rules", nil,
+		#   @xcapclient.get_node("pres-rules", nil,
 		#     '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
 		#     {"cp" => "urn:ietf:params:xml:ns:common-policy"})
 		#
 		# If success:
-		# * The method returns the response body as a String.
+		# * The method returns the node as a String.
 		#
-		def get_element(auid, document, selector, xml_namespaces=nil, check_etag=true)
+		def get_node(auid, document, selector, xml_namespaces=nil, check_etag=true)
 			
 			application, document = get_app_doc(auid, document)
 			response = send_request(:get, application, document, selector, nil, xml_namespaces, nil, check_etag)
@@ -270,11 +270,11 @@ module XCAPClient
 			
 		end
 		
-		# Create/replace an element in the document stored in the server.
+		# Create/replace a node in the document stored in the server.
 		#
-		# Example:
+		# Example, creating/replacing the node with "id" = "sip:alice@example.org":
 		#
-		#   @xcapclient.put_element("pres-rules", nil,
+		#   @xcapclient.put_node("pres-rules", nil,
 		#     '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:bob@example.org"]',
 		#     '<cp:one id="sip:bob@example.org"/>',
 		#     {"cp"=>"urn:ietf:params:xml:ns:common-policy"})
@@ -283,7 +283,7 @@ module XCAPClient
 		# * The method returns true.
 		# * Local plain document and ETag are deleted (as the document has changed).
 		#
-		def put_element(auid, document, selector, selector_body, xml_namespaces=nil, check_etag=true)
+		def put_node(auid, document, selector, selector_body, xml_namespaces=nil, check_etag=true)
 			
 			application, document = get_app_doc(auid, document)
 			response = send_request(:put, application, document, selector, selector_body, xml_namespaces, "application/xcap-el+xml", check_etag)
@@ -297,11 +297,11 @@ module XCAPClient
 		end
 		
 		
-		# Delete an element in the document stored in the server.
+		# Delete a node in the document stored in the server.
 		#
-		# Example:
+		# Example, deleting the node with "id" = "sip:alice@example.org":
 		#
-		#   @xcapclient.delete_element("pres-rules", nil,
+		#   @xcapclient.delete_node("pres-rules", nil,
 		#     '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
 		#     {"cp" => "urn:ietf:params:xml:ns:common-policy"})
 		#
@@ -309,7 +309,7 @@ module XCAPClient
 		# * The method returns true.
 		# * Local plain document and ETag are deleted (as the document has changed).
 		#
-		def delete_element(auid, document, selector, xml_namespaces=nil, check_etag=true)
+		def delete_node(auid, document, selector, xml_namespaces=nil, check_etag=true)
 			
 			application, document = get_app_doc(auid, document)
 			response = send_request(:delete, application, document, selector, nil, xml_namespaces, nil, check_etag)
@@ -323,15 +323,101 @@ module XCAPClient
 		end
 		
 		
-		# Fetch the namespace prefixes of an element.
+		# Fetch a node attribute from the document stored in the server.
+		#
+		# Example, fetching the "name" attribute of the node with
+		# "id" = "sip:alice@example.org":
+		#
+		#   @xcapclient.get_attribute("pres-rules", nil,
+		#     '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
+		#     "name",
+		#     {"cp" => "urn:ietf:params:xml:ns:common-policy"})
+		#
+		# If success:
+		# * The method returns the attribute as a String.
+		#
+		def get_attribute(auid, document, selector, attribute_name, xml_namespaces=nil, check_etag=true)
+			
+			application, document = get_app_doc(auid, document)
+			response = send_request(:get, application, document, selector + "/@#{attribute_name}", nil, xml_namespaces, nil, check_etag)
+			
+			# Check Content-Type.
+			check_content_type(response, "application/xcap-att+xml")
+			
+			return response.body.content
+			
+		end
+		
+		
+		# Create/replace a node attribute in the document stored in the server.
+		#
+		# Example, creating/replacing the "name" attribute of the node with
+		# "id" = "sip:alice@example.org" with new value "Alice Yeah":
+		#
+		#   @xcapclient.put_attribute("pres-rules", nil,
+		#     '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
+		#     "name",
+		#     "Alice Yeah",
+		#     {"cp" => "urn:ietf:params:xml:ns:common-policy"})
 		#
-		# If the client wants to create/replace an element, the body of the PUT request must use the same namespaces and prefixes as those used in the document stored in the server. This methods allows the client to fetch these namespaces and prefixes.
+		# If success:
+		# * The method returns true.
+		# * Local plain document and ETag are deleted (as the document has changed).
+		#
+		def put_attribute(auid, document, selector, attribute_name, attribute_value, xml_namespaces=nil, check_etag=true)
+			
+			application, document = get_app_doc(auid, document)
+			response = send_request(:put, application, document, selector + "/@#{attribute_name}", attribute_value, xml_namespaces, "application/xcap-att+xml", check_etag)
+			
+			# Reset local plain document and ETag as we have modified it.
+			document.plain = nil
+			document.etag = nil
+			
+			return true
+			
+		end
+		
+		
+		# Delete a node attribute in the document stored in the server.
+		#
+		# Example, deleting the "name" attribute of the node with
+		# "id" = "sip:alice@example.org":
+		#
+		#   @xcapclient.delete_attribute("pres-rules", nil,
+		#     '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
+		#     "name",
+		#     {"cp" => "urn:ietf:params:xml:ns:common-policy"})
+		#
+		# If success:
+		# * The method returns true.
+		# * Local plain document and ETag are deleted (as the document has changed).
+		#
+		def delete_attribute(auid, document, selector, attribute_name, xml_namespaces=nil, check_etag=true)
+			
+			application, document = get_app_doc(auid, document)
+			response = send_request(:delete, application, document, selector + "/@#{attribute_name}", nil, xml_namespaces, nil, check_etag)
+			
+			# Reset local plain document and ETag as we have modified it
+			document.plain = nil
+			document.etag = nil
+			
+			return true
+			
+		end
+		
+		
+		# Fetch the namespace prefixes of a node.
+		#
+		# If the client wants to create/replace a node, the body of the PUT
+		# request must use the same namespaces and prefixes as those used in 
+		# the document stored in the server. This methods allows the client
+		# to fetch these namespaces and prefixes.
 		#
 		# Related documentation: {RFC 4825 section 7.10}[http://tools.ietf.org/html/rfc4825#section-7.10], {RFC 4825 section 10}[http://tools.ietf.org/html/rfc4825#section-10]
 		#
 		# Example:
 		#
-		#   @xcapclient.get_element_namespaces("pres-rules", nil,
+		#   @xcapclient.get_node_namespaces("pres-rules", nil,
 		#     '/ccpp:ruleset/ccpp:rule[@id="pres_whitelist"]',
 		#     { "ccpp" => "urn:ietf:params:xml:ns:common-policy" })
 		#
@@ -347,7 +433,7 @@ module XCAPClient
 		#   {"pr"=>"urn:ietf:params:xml:ns:pres-rules", "cp"=>"urn:ietf:params:xml:ns:common-policy"}
 		# If not, the method returns the response body as a String and the application must parse it.
 		#
-		def get_element_namespaces(auid, document, selector, xml_namespaces=nil, check_etag=true)
+		def get_node_namespaces(auid, document, selector, xml_namespaces=nil, check_etag=true)
 			
 			application, document = get_app_doc(auid, document)
 			response = send_request(:get, application, document, selector + "/namespace::*", nil, xml_namespaces, nil, check_etag)
@@ -373,7 +459,7 @@ module XCAPClient
 		#
 		def get_xcap_auids
 		
-			body = get_element("xcap-caps", nil, '/xcap-caps/auids')
+			body = get_node("xcap-caps", nil, '/xcap-caps/auids')
 			
 			return case NOKOGIRI_INSTALLED
 				when true
@@ -391,7 +477,7 @@ module XCAPClient
 		#
 		def get_xcap_extensions
 		
-			body = get_element("xcap-caps", nil, '/xcap-caps/extensions')
+			body = get_node("xcap-caps", nil, '/xcap-caps/extensions')
 			
 			return case NOKOGIRI_INSTALLED
 				when true
@@ -409,7 +495,7 @@ module XCAPClient
 		#
 		def get_xcap_namespaces
 		
-			body = get_element("xcap-caps", nil, '/xcap-caps/namespaces')
+			body = get_node("xcap-caps", nil, '/xcap-caps/namespaces')
 			
 			return case NOKOGIRI_INSTALLED
 				when true
@@ -498,7 +584,7 @@ module XCAPClient
 			
 			# Body (just in case of PUT).
 			body = ( selector_body || document.plain || nil ) if method == :put
-			raise ArgumentError, "PUT body empty" unless String === body if method == :put
+			raise ArgumentError, "PUT body must be a String" unless String === body if method == :put
 			
 			begin
 				response = @http_client.request(method, uri, nil, body, extra_headers)
@@ -532,11 +618,14 @@ module XCAPClient
 			when "412"
 				raise HTTPNoMatchingETag
 			
-			when "500"
+			when /^50[03]$/
 				raise HTTPServerError
+			
+			whe "501"
+				raise HTTPNotImplemented
 				
 			else
-				raise HTTPUnknownError, "Unknown error for URI '#{uri}' [#{response.status} #{response.reason}]"
+				raise HTTPUnknownError, "Unknown Error [#{response.status} #{response.reason}]"
 				
 			end
 			

data/lib/xcapclient/errors.rb

@@ -15,6 +15,7 @@ module XCAPClient
 			class HTTPWrongContentType < HTTPError ; end
 			class HTTPBadRequest < HTTPError ; end
 			class HTTPServerError < HTTPError ; end
+			class HTTPNotImplemented < HTTPError ; end
 			class HTTPUnknownError < HTTPError ; end
 		class XMLParsingError < XCAPClientError ; end
 	

data/lib/xcapclient.rb

@@ -1,6 +1,6 @@
 module XCAPClient
 	
-	VERSION = "1.0"
+	VERSION = "1.1"
 	
 	RUBY_VERSION_CORE = case RUBY_VERSION
 		when /^1\.9\./

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: xcapclient
 version: !ruby/object:Gem::Version 
-  version: "1.0"
+  version: "1.1"
 platform: ruby
 authors: 
 - "I\xC3\xB1aki Baz Castillo"
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-07-31 00:00:00 +02:00
+date: 2009-11-09 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -44,11 +44,13 @@ files:
 - README.rdoc
 - ERRORS.rdoc
 has_rdoc: true
-homepage: http://dev.sipdoc.net/projects/ruby-xcap-client/wiki/
+homepage: http://dev.sipdoc.net/projects/ruby-xcapclient/wiki/
 post_install_message: 
 rdoc_options: 
 - --main
 - README.rdoc
+- --title
+- XCAPClient Documentation
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement