The Places service is intended to provide a general mechanism for
storing geographic information. Any place may have a
latitude/longitude pair, which would allow radius searches based
on ZIP codes or any other place that carries a latitude/longitude
pair. Places keeps track of various
different place types, and maintains their hierarchical
relationships independent of application logic (e.g. it knows that
Wisconsin isn't in Albania so that your application doesn't have
to). The most interesting place type to most applications, however,
is the address, and its supporting PL/SQL and Tcl APIs.
Places allows an application to generate address entry and display
widgets, validate the integrity of user-defined addresses via a
standard ad_page_contract pluggable filter, insert
or update address values in the database without knowledge of the
underlying structure, and associate addresses with
application-specific objects. Places ships (as of this writing) with a
complete set of countries (including ISO codes), US states
and protectorates (with USPS abbreviations), US counties and
US ZIP codes which can be used
to create widgets and provide parents for application-defined
places and place-types.
Most geographically-oriented applications should make use of the Places service for storing their place data. In addition to the direct advantages of self-maintained place-containment integrity, latitude/longitude support and out-of-the box country and state data, geographic information that is stored via the Places service is readily available to other applications and services that may choose to extend the custom application or service in the future. In cases where these benefits do not outweigh the value of a very specific and highly-customized and/or tuned storage mechanism, use of the Places service may be limited or foregone altogether.
Places will be immediately useful to applications such as Address Book that will be able to use the address object without worrying about what goes on under the hood. Also, a geocentric bboard application could tie into Places to define bboards for specific regions, states, counties, zip codes, or any other place type.
The Places service meets the need for a hierarchical storage mechanism by providing a place subtype of acs_object, which is subtyped by country, region, us_county, postal_code, municipality, and address, and is intended to be subtyped further by other applications. us_state is itself a subtype of region. The hierarchy is glued together using two relationships. First is the subplace relation. This identifies a place as a component of another place. A place may only be a direct component of one parent place (e.g. Massachusetts may not belong to both Singapore and the United States), but it is transitive, so an address that is defined in Arkansas is understood to be within the United States. The second relationship is the location relation. This associates an object with a place. It is transitive as well, so a geocentric bboard entry with a location relationship to the state of Georgia would also be related to the United States as a whole. Places also provides a more manageable address API by allowing application programmers to define an address with a state and country in one step. The API then verifies the hierarchy integrity and creates the appropriate subplace relationship. Also, views are provided to allow application programmers to retrieve the state and country information without traversing the hierarchy.
Aware that transitive relationships such as the subplace and location relations would require expensive Oracle CONNECT BY queries in a fully normalized implentation, we chose to follow the methods of the already load-tested ACS parties mechanism. All relationships, both direct and indirect between places, subplaces and other ACS objects are stored in a single trigger-maintained index-organized table for very fast queries up and down the place hierarchy.
This is a performance improvement relative to a standard hierarchy, but it does lose a bit of speed relative to a non-hierarchical system. One comparison that could be made is to the ACS3.x address-book application. Addresses in ACS3.x were represented in a single table, including fields for state abbreviation and country ISO code, so a query like "show me all the addresses in the state abbreviated as FL" could be posed without joining with other tables to provide this information. Under the Places service, such a query would have to join against the index to retrieve that information. In fact, there is a view provided in the Places service that makes this process transparent, so an application can easily use Places in the same way that they might have used an address-book entry under 3.x. The extra join required is not actually as big a problem as it might seem. If an implementation of Places is discovered to lag on such queries, the addresses table itself could be denormalized to provide this data in a flat representation. We already provide an API for creating addresses in what appears to the application to be the flat ACS3.x style. These API calls and the view mentioned earlier could be adapted to maintain and use the denormalized City/State/Country information. The result is that Places can have its cake and eat it too. It maintains a hierarchical representation of places in exchange for a little bit of insert and update overhead, something that should be completely forgiveable in almost any implementation, as query speed would almost certainly be the greater impediment to application performance.
Another major advantage of this system over ACS3.x, and in fact, most address storage mechanisms from PDA address books to e-commerce sites is the capability for an application or client site to define locale-specific place-types. If you are building an e-commerce site with international order fulfillment, this could be very useful. Provinces of target countries could be loaded into the Places service, address widgets could be templated to the new specifications, and a site could easily free itself from the US-centric traditions of web development. Places allows for creation of an arbitrary hierarchy depth as well. An address in Monaco doesn't need to belong in a region of the country in order to highly geographically specific, so an address in Monaco could belong directly to the country, where an address in the United States might want to be a subplace of a region, a state, a county, a city and a zip code (note that most of these place types are not defined by default, but could easily be added if the data were provided).
The Places service provides very little end-user UI. Only address entry widgets and display widgets are provided. Surprisingly, the biggest enhancement in user experience over a flat address storage mechanism is provided by a system that provides no UI itself: the address validation process. When an address is validated, it accepts fields for city, state, postal code, country etc. Already if you select a state name from the dropdown without choosing a country, the address will be placed in the appropriate country as well. If a ZIP code database were loaded into Places along with cities and a simple modification were made to the validation code, a user could enter their one-line street address and ZIP code. Places would do the rest and put the address in the appropriate city, state and country. Additionally, if extra place types such as national segments were defined in the hierarchy, the address could be referenced relative to those automatically, making it possible for application programmers to, for example, generate targeted mailing lists of users in the Southwestern US employing other application specific criteria such as interests or income ranges.
From a programming standpoint, Places was designed for ease of application implementation as well as the inherent robustness in a hierarchical model. By providing straightforward SQL views, PL/SQL and Tcl APIs, an application may store addresses, relate them to its objects, and display the stored addresses without knowing or caring that an address is a complex hierarchical data structure. At the same time, another programmer can get down to the root of the service and deal directly with the underlying structures for highly specific and demanding applications.
subplace_rel: The Subplace Relation - subtype of acs_relnew/delete
functionality.move function that
takes a subplace's place_id, the
place_id of
its original container, and a new container's place_id.
It returns the rel_id of the newly created relation.
This would be useful if an address was modified to be in
another zip code or state.violation function that returns
null if subplace_id is either a
direct or indirect subplace of the place identified by place_id, otherwise
a meaningful error message.
This is used primarily by other validation processes.place_element_map - A mapping of all direct and indirect
place-subplace and place-locatee
relations. This view is shared by location_rel, as data from
both relation types is displayed.place_subplace_map - A mapping of all direct and indirect
place-subplace relations.location_rel: The Location Relation - subtype of acs_relnew/delete
functionality. The new function does not allow
the application access to the value of sort_key,
however. Sort key integrity is maintained by the relation itself.
To insert a location_rel before another relation pertaining to the
same acs_object, you simply enter a before_rel_id
parameter. If before_rel_id is not specified, the relationship
is assigned a sort_key higher than all the others pertaining to the same
object. The use_context parameter exists to allow
applications to define textual keys to determine the function that
the relationship serves. A typical use_context might
be 'mailing' for a mailing address associated with an
order in an e-commerce application.move function that
takes a locatee's locatee_id, the
place_id of
its original location, and a new location's place_id.
It returns the rel_id of the newly created relation.
This would be useful if an object were to change locations, such as
an office relocating.
sort_key
itself, there is a swap_sort procedure, which allows any two
relations pertaining to the same object to be swapped in terms of sort
order.place_element_map - A mapping of all direct and indirect
place-subplace and place-locatee
relations. This view is shared by subplace_rel, as data from
both relation types is displayed.place_locatee_map - A mapping of all direct and indirect
place-locatee relations.place: Place Object-type - subtype of acs_objectnew/delete functionality.
The new function adds the ability to create a place
as a subplace of another place in a single step by taking
superplace_id as an optional argument. This works by intrinsically
calling subplace_rel.new after creating the place. Also,
a place may be created and associated with an acs_object
in a single step, as the new function also takes an
optional locatee_id along with the optional fields associated
with that relationship (use_context and before_rel_id).country: Country Object-type - subtype of placenew/delete functionality as
extended by the place object.name function.country_id
country_id.region: Region Object-type - subtype of placenew/delete functionality as
extended by the place object.name function.us_state: US State Object-type - subtype of regionnew/delete functionality as
extended by the region object.name function.state_id.state_id.us_county: US County Object-type - subtype of placenew/delete functionality as
extended by the place object.name function.postal_code: Postal Code Object-type - subtype of placenew/delete functionality as
extended by the place object.name function.postal_code_id.postal_code_id of
a given postal code.municipality: Municipality Object-type - subtype of placenew/delete functionality as
extended by the place object.name function.address: Address Object-type - subtype of placenew/delete functionality as
extended by the place object.name function.violation function that returns a textual error message
if the address described is invalid, or null if everything is ok.smallest_superplace_id function that returns
the place_id of the smallest valid superplace. This function is
used by the new_intl function to determine what superplace to put the
newly generated address into.new_intl function that acts similarly to the
new function, except that it takes optional postal_code_id,
region_id and
country_id codes instead of a superplace_id for automatic validation and
placement on the place hierarchy.update_intl procedure to update an address entry. This does
hierarchy validation and makes subplace_rel.move calls as appropriate.addresses_complete - A flat view of all addresses in the database providing
state abbreviations and country ISO codes as if they were part of the table itself.addresses_located - A wrapper around addresses_complete that
returns all addresses that serve as locations, along with the objects to which they are related
and the relationships' use_context and sort_key values.
The Places service was designed with programmer efficiency in mind, and as
such, most legal transactions may be performed using the PL/SQL and Tcl
API calls detailed above. Places is a fundamental service, and
leaves permissioning (including security context, etc) to the application
programmer. Any operation on the tables defined in places-create.sql
is legal, with the exception of updates on the subplace_rels,
location_rels and any operation (insert, update or delete) on
place_element_index. Much like the groups data model,
a trigger-maintained index of the hierarchy that they define must be kept. The
triggers would be inordinately complex for an update operation, and the insert and
delete triggers certainly
wouldn't take kindly to manual alteration of the index. Also, with the API
provided, there should be no need to modify the sort_key column of
the location_rels table. If your application chooses to do so, please
be careful to follow the tenets of ACID (you can leave the durability part
to Oracle, but it would be remarkably easy to fall short on atomicity, consistency
and isolation). In short, all transactions
that make sense in the context of your application that may be safely carried out
relative to the places service and its other dependent applications are legal.
Only state, country and address widgets are provided directly by Places. The Places service relies on application programmers to make appropriate use of the widgets provided.
Places requires no special configuration.
| Document Revision # | Action Taken, Notes | When? | By Whom? |
|---|---|---|---|
| 0.1 | Creation | 12/15/2000 | John Mileham |
| 0.2 | Revised and overhauled for Places alpha2 release | 12/15/2000 | John Mileham |