Section 6.2. Understanding Entities and Entity Relationships


6.2. Understanding Entities and Entity Relationships

Entities in MapPoint Web Service represent real things (e.g., countries, cities, landmarks, schools) that exist in the real world. All entities are first-class citizens in the world of MapPoint Web Service; they have type definitions, carry their own identities, enjoy entity-level find capabilities, maintain relationships, and in some cases even persist their identity across different versions of MapPoint Web Service.

Before I get into too many details, here is an example to help you understand this concept. Consider the United States: in MapPoint Web Service, the country is an entity with entity ID 244; the states contained within it are represented as children entities to the United States entity. Counties, cities, and towns within these states are represented as the children entities to the state entities; this parent-child relationship continues down to things like bridges, roads, parks, and schools. Figure 6-1 summarizes this discussion by showing the entity relationships for the town of Redmond, WA.

How do all the entities and entity relationships defined in MapPoint Web Service help you? The short answer is that you can issue smarter and more focused find queries to find things that suit your needs. Many applications require you to drill down into the subgeographic areas starting with a larger coverage. To continue with our United States example, you may want to develop an application where your customers start with the United States, go to the 50 states in the United States, pick a state and get all counties, pick a county and get all cities, and pick a city and get all interested entities within it. Entities are used to issue queries with limited geographic context (such as all states within the United States). You can also add your own custom entity types (or points of interest) that allow you to find places using the entities and entity relationships.

Figure 6-1. Entity parent-child relationships


Programmatically, all entities are represented by the Entity class, and the definition of an entity type is represented by the EntityType class. The EntityType objects define the schema of an entity type, including the name, parent, and valid properties of an entity type.

Each physical entity represented using the Entity class has an ID, a DisplayName, which is a long descriptive name, and a common short Name. An Entity object also indicates the type of entity using the TypeName field (which is a string); this type name maps to a corresponding EntityType object. Finally, an Entity object exposes a collection of properties specific to that entity type as an array of EntityPropertyValue objects. The EntityPropertyValue object is a simple name value pair that gives you the name and value of the property. If you know an entity's properties, you can issue queries to find entities by their propertieswe will look at this concept later in this chapter.

If you find the concepts of EntityType and Entity confusing, think of it this way: an EntityType defines the schema, and an Entity represents the instance of a "thing" with that schema (similar to the difference between a class and an object). For example, the entity type PopulatedPlace defines the schema and parent-child relationships for geographic entities such as cities, towns, and villages; the entity type PopulatedPlace is represented by the EntityType class programmatically. The city of Paris is an entity of type PopulatedPlace, so the actual city is represented by an Entity object programmatically with a TypeName of PopulatedPlace.

6.2.1. Data Sources and Entity Types

Because entities in MapPoint Web Service are real things, they are contained in corresponding data sources for any given geographic extent. For example, if you consider the North American map data source MapPoint.NA, entities within the United States, Canada, Mexico, and Puerto Rico are contained in this data source. The only way to get to these entities is by knowing which entity types are supported by a particular data source. To find out which entity types are supported by a given data source, use the CommonServiceSoap method to get a list of the entity types supported by different data sources.

6.2.1.1. Getting all supported entity types within a data source

You can get a list of entity types supported by a specific data source using the CommonServiceSoap.GetEntityTypes method, which takes the data source name as an input argument and returns an array of EntityType objects. The following code snippet shows how to get all entity types defined in the MapPoint.NA data source:

     //Define an instance of CommonServiceSoap class     CommonServiceSoap commonService = new CommonServiceSoap( );     //Assign credentials     . . .     //Define a local entitytypes array     EntityType[] entityTypes;     //Datasource in question     string datasource = "MapPoint.NA";     //Get all entity types using the GetEntityTypes method      entityTypes = commonService.GetEntityTypes(datasource);     //Now loop through each entity display the name, parent     foreach(EntityType et in entityTypes)     {         Console.WriteLine(et.Name);         Console.WriteLine(et.Definition);         Console.WriteLine(et.ParentName);     }

Along the same lines, you can also get all entity type definitions for all data sources in MapPoint Web Service environment:

     //Create an instance of common service soap     CommonServiceSoap commonService = new CommonServiceSoap( );     //Assign credentials     . . .     xDataSource[] dataSources;     dataSources = commonService.GetDataSourceInfo(null);     foreach (DataSource ds in dataSources) {     String datasource = ds.Name;     //Now get entity type info for this data source     //Define a local entitytypes array     EntityType[] entityTypes;     //Datasource in question     //Get all entity types using the GetEntityTypes method      entityTypes = commonService.GetEntityTypes(datasource);     //Now loop through each entity display the name, parent     foreach(EntityType et in entityTypes)      {        Console.WriteLine(et.Name);        Console.WriteLine(et.Definition);        Console.WriteLine(et.ParentName);       }     }

I use the CommonServiceSoap.GetDataSourceInfo method to get a list of data sources and then the CommonServiceSoap.GetEntityTypes method to get a list of entity types defined in each data source.

Once you know the names of the entity types, you can use the Find APIs, which we will see in detail later in the chapter, to customize the find queries to find only particular entity types.




Programming MapPoint in  .NET
Programming MapPoint in .NET
ISBN: 0596009062
EAN: 2147483647
Year: 2005
Pages: 136
Authors: Chandu Thota

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net