** WPSC_Data_Map class **

Much of the countries/regions/currency efficiency gains comes from not reloading the same data from the database multiple times.  Once data is loaded it is stored into a construction that provides easy access to highly structured data, and can save and restore itself from persistent cache as needed.  The class only loads the data it needs

In support of these enhancements to the country / regions / currency class it was useful to create a general purpose object that did these things.

* could return a value from a list of values based on a unique identifier
* could retain its list of values throughout a transactions execution without having to go back to a database
* could be smart enough restore its list of values from a cached copy of itself only if it was necessary, and without a client needing to initiate the save
* could automatically save itself when appropriate, and without a client object needing to initiate the save
* could automatically recreate itself should it be the case that  the cached copy its data was no longer available

And thus was born the WPSC_Data_Map Class
** WPSC_Currency class **

Access all information about a currency creating a WPSC_Currency object.  No longer a need to do database queries to WPSC_TABLE_REGION_TAX. Information is retrieved from the WPSC_Countries object which maintains a cache used by a geographic classes.

Creating a currency object:
new WPSC_Currency ( $currency_name )

As an example, if you have a currency name in hand, you can find all information by doing
$wpsc_currency = new WPSC_Currency (  ‘USD’ );

If you are working with a country there is also an easy way to get the currency for that country through the WPSC_Country class

$wpsc_currency = $wpsc_country->currency();
** WPSC_Region class **

Access all information about a region by creating a WPSC_Region object.  No longer a need to do database queries to WPSC_TABLE_REGION_TAX. Information is retrieved from the WPSC_Countries object which maintains a cache used by a geographic classes.

Creating a region object:
	new WPSC_Region ( $country_id_or_isocode, $region_id_or_code )

As an example, you can find all about massachussets my doing any of the following,
	$ma = new WPSC_Region ( ‘US’, ‘MA’ )
	$ma = new WPSC_Region ( ‘US’, 34 )
	$ma = new WPSC_Region ( 136, ‘MA’ )
	$ma = new WPSC_Region ( 136, 34 )
	$ma = new WPSC_Region ( null, ‘34’ )

The class can also be used to create a new region in the database:
	$ma = WPSC_Region( ‘US’,, array( 'code' => 'MA', 'name' => 'Massachussets ', 'tax' => 6.5, )
** WPSC_Country class **

Access all information about a country by creating a WPSC_Country object.  No longer a need to do database queries to WP_TABLE_CURRENCY_LIST . Information is retrieved from the WPSC_Countries object which maintains a cache used by all geographic classes.

Creating a currency object:
	new WPSC_Country(  $country_id_or_isocode )

You can create a country object if you know string country ISO code, or the unique integer country id.

As an example, if you have a currency name in hand, you can find all information by doing something like this:
	$usa = new WPSC_Country( ‘US’ );

Which is the same as doing this:
	$usa = new WPSC_Country( 136 );

If a new country needs to be created or updated, pass an array of attribute value pairs to the country class.

	$wpsc_country = new WPSC_Country(
		array(											  						'country' 	=> 'Atlantis',
			'isocode' 	=> 'AA',
			'currency' 	=> 'Sand Dollar',
			'symbol' 	=> '$',
			'symbol_html' 	=> '&#036;',
			'code' 		=> 'ASD',
			'has_regions' 	=> false,
			'tax' 		=> 80,
			‘continent' 	=> 'Atlantis',
			)
		)
	);

Class does not allow direct access to properties.  However, if your code desires to use the individual country properties you can easily get an array with them us the as_array() method. 	 You can even 'explode' this to get individual variables each with the country property value.
** WPSC_Countries class **

Before your read to much farther , if you want to do things with countries, regions or currencies you want to take a look at these classes:

    WPSC_Country  - found in file wpsc-country.class.php
    WPSC_Region   - found in file wpsc-regions.class.php
    WPSC_Currency - found in file wpsc-currency.class.php

These three classes make up the bulk of developer facing classes. After reviewing these classes the login within the WPSC_Countires class will have context.

*About WPSC_Countries:
WPSC_Countries is a WPeC class used to provide easy access to country, region and currency information for all of WPeC an any extensions. Because this data isus  eoften throughout WPeC it is designed to be quick, memory efficient and avoid accessing the database.

The primary purpose of the is class is to centralize the access to country/region/currency data, act as a service provider for access of the data, act as a central place to keep the data set to avoid replicating it many times during execution of the code, and in the end make it very fast and efficient to work with country/region/currency data.

This class is largely procedural, and has many static methods that let the caller get access to country/region/currency data.

*A Note to you OOP purists:
Yes, if you are looking for this can be thought of as a singleton class, as could some aspects of the prior implementation of the WPSC_Country class that have been migrated to here. Only one of these  lasses is entirely appropriate until we start supporting e-commerce from other planets. At that time each planet would have it's own WPSC_Countries class object.  Until that happens the more pervasive use of static variables and methods improves performance enough to make it worthwhile.  I personally promise to make the necessary changes prior to having to support e-commerce to/from the Mars colony.

*How does it work?
This class uses the static currency and region information distributed with WPeC to create an
object that is optimized for access.  A copy of this object is cached.  When WPeC initialized
this cached object is retrieved and used to service any request for geographical data.

*How is this data refreshed if it is cached?
If an administrator changes country data in the WPeC admin tool the object will be rebuilt. If
WPeC is upgraded the object will be rebuilt. And, because the object is stored as a transient, any action that would refresh the WordPress object cache would cause the object

*Where is the global so I can access this data?
I'm not telling! (just kidding) ... There isn't one because I hate globals (and I want you to hate globals also).

You access geography data through the static methods available in WPSC_Countries, or by instantiating objects of type WPSC_Country, WPSC_Region, and WPSC_Currency

*What about the database?
Can you identify the film this quote comes from? ... Forget about Dave. For our immediate purposes, there is no Dave. Dave does not exist.

*Why is that important?
Forget about database. For our immediate purposes, there is no database. database does not exist.

If you use the functionality in this module it is unlikely you will need to find the data storage for the raw geography data. But, If you do any kind of update or modify operation on any of the data that this class uses please invoke the “clear_cache()” method so that the object can refresh itself.

*Before this class existed the direct queries to the database where really simple. Did creating this module really help?
uhhh, Yes. The checkout page was used as a benchmark.  When this class was there were almost 200 fewer queries to the database on just that page. Besides that there was a lot of duplicated code scattered about WPeC do get the data from the database. Much of that code had subtle variations that made it hard to maintain.

Any other benefits to this module over direct to database
Going direct the database prevented us from improving the mechanism used to store and distribute country data and updates without changing a lot of code.  Now all the database access is centralized we can make some improvements when we have time

The WPeC Geography implementation consists of four class

	WPSC_Country - Get anything about a single country you might want to know
	WPSC_Region - Get anything about a single region you might want to know
	WPSC_Currency - Get information about a currency
	WPSC_Countries - Get lists of countries, convert key fields to unique ids, and other useful functions. Also abstracts data storage mechanism from
Inlcude new WPeC geography classes
Added WPSC_Countires, WPSC_Country, WPSC_Region and WPSC_Currency classes to the global includes
Updated WPeC to use WPSC_Countries, WPSC_Country, WPSC_Reagion and WPSC_Currency
Merge remote-tracking branch 'upstream/master' into pr-customer-meta-checkout-country-region-currency
Merge branch 'pr-customer-meta-checkout-country-region-currency' into dev-master

Conflicts:
	wpsc-admin/settings-page.php
	wpsc-core/wpsc-includes.php
	wpsc-includes/wpsc-countries.class.php
	wpsc-includes/wpsc-country.class.php
	wpsc-includes/wpsc-currency.class.php
	wpsc-includes/wpsc-region.class.php