Login | Register   
LinkedIn
Google+
Twitter
RSS Feed
Download our iPhone app
TODAY'S HEADLINES  |   ARTICLE ARCHIVE  |   FORUMS  |   TIP BANK
Browse DevX
Sign up for e-mail newsletters from DevX


advertisement
 

Upload Custom Data to the MapPoint Web Service Site with Java

For this hands-on lesson in using Java to connect to the MapPoint Web Service, we show you how to use the MapPoint Customer Service Site, which lets you upload your own custom data sources so you can geocode and search for your own store location or special points of interest.


advertisement
he Microsoft MapPoint Web Service lets you use industry-standard Web Service methods to interact with the extensive MapPoint database. However, if you are a MapPoint Web Service customer, you can also access the MapPoint Customer Service Site. The Customer Service Site lets you upload your own custom data sources. Custom data sources let you geocode and search for your own store location or special points of interest.



In this whitepaper, we will look at the Customer Service Site and see how to use Java-based Web Services to upload a custom data source.

The sample code illustrates the Java Web Services and a sample flat data file.



The Customer Service Site
Prior to MapPoint Web Service version 3.5, if you wanted to provide directions to a list of your stores, you had to:

  1. Manually geocode each of your store locations
  2. Store the data locally
  3. Perform a Web Service call to geocode the starting address, getting latitude and longitude.
  4. Write your own logic to determine which of your stores was closest
  5. Perform a Web Service call to get directions between the starting address and your store address.
Thanks to the new features in MapPoint version 3.5, you can use the Customer Service site to create a custom data source which will automatically geocode your store locations, store your data on the MapPoint server, and let you use standard MapPoint Web Service calls to find out which store is closest to a particular address. In other words, a custom data source dramatically reduces the amount of effort you have to spend to build a store locator.

The Customer Service Site also offers many other services related to your MapPoint account. For example, you can use the site to check your credentials, upload and manage custom icons for display on a map, manage all of your custom data sources, and view reports on how your MapPoint Web Service account is being used.

Accessing the Customer Service Site
In order to access the MapPoint Customer Service Site, you need partner credentials, which are provided when you sign up for a MapPoint Account. Partner credentials are different from the ordinary MapPoint Web Service credentials. The partner credentials are used exclusively for accessing the MapPoint Customer Service Site, whereas the MapPoint Web Service credentials are used exclusively for calling the Find, Route, Render and Common Web Services. Your partner credentials will consist of a user name and a password.

If you need to know how to sign up for a MapPoint account, or can't find your partner credentials, contact your MapPoint sales associate.

Once you have your credentials, you can access the MapPoint Customer Service Site. You will be prompted for your credentials. In order to access, the site, you need to preface your user name with the "partners" domain (e.g. partners/myusername). Once you have logged in, you will see a list of all of your recent jobs and custom data sources. We'll examine this list in greater detail later. For now, take a look at the menu options on the left side of the portal. You can use these options to perform various MapPoint related tasks.

Check Credentials
Use this if you need to make sure your MapPoint Web Service credentials are valid.

Upload and Manage Icons
The MapPoint Web Service allows you to select from hundreds of standard pushpin icons. However, you can use the Customer Service Site to upload your own custom icons. Custom icons let you determine how points of interest will be displayed on any map that you render with the MapPoint Web Service. For more information, including the icon formats, see the Upload Custom Icons section on the Customer Service Site.

Upload and Manage Location Data
One of the main reasons to use the Customer Service Site is to create your own custom data sources. A custom data source allows you to upload your own locations (e.g. stores), provide searchable data on the locations and geocode the locations. Once you have a custom data source, you can search it using the ordinary MapPoint Web Service methods. You can even create directions and route to your locations as if they were part of the default MapPoint data set. In other words, you can use custom data sources to expand MapPoint's knowledge and customize return values for your particular company.

With version 3.5, you can create and maintain up to 25 custom data sources, each with as many as 8 million searchable cells. The actual amount of data you can store depends on the size and shape of your files. The file formats will be discussed later, however you can use either XML or flat files. Although you can manually upload your data source through the Customer Service Site, you will most likely want to use the Customer Data Service Web Service.

View Reports
If you want to know how your MapPoint Web Service account is being used, you can check the reports on the Customer Service Site. These reports let you see which business locations have been requested, which search properties were most popular, and which regions (zip code, MSA, subdivision, country, etc) were examined most often. You can also view hourly, daily or monthly reports on transactions by service and transactions by customer defined field. Finally, you can look at the success rates for your various Web Service calls. You can only access report data through the Customer Service Site; however, you can download any report into a comma-separated file or as a Microsoft Excel spreadsheet so you can share selected data with others.

The Customer Data Service Web Services
Although you can create and manage MapPoint Web Service custom data sources through the Customer Service Site, you may wish to automate the process. Thanks to the Customer Data Service, you can use Web Services to create new data sources and update existing data sources. We will take a much closer look at the Customer Data Service and see how to use Java to create an automated process for uploading custom data.

If you want to know how to use the Web Service in C#, please see the DataUploadClient in the MapPoint 3.5 SDK. You can also find the SDK online.

Before You Start Using Java
Before you can use Java to access the MapPoint Customer Service Site, you need to set up several prerequisites. In particular, you will need to ensure that your MapPoint accounts are valid and that you have a proper Java environment.

MapPoint Accounts
In order to use the Customer Data Service, you will need to know your Customer Service Site credentials. You can verify that you have the correct credentials by:

  1. Browse to https://mappoint-css.partners.extranet.microsoft.com/cscv3/Css.aspx.
  2. You should be asked to provide a user name and password. Make sure you preface your user name with the "partners" domain. (e.g. partners/username).
  3. If your credentials are valid, you should see the Customer Service Site home page, which displays announcements and shows you all recent upload jobs and custom data sources. The menu on the left lets you verify your MapPoint Web Service credentials, view reports, and upload or manage custom icons.
If you want to test your custom data source, you will also need the user name and password for your MapPoint Web Service account. The MapPoint Web Service username should be a 5 digit number.

Java Components
In order to call the Customer Data Service using the code in this article, you will need:

  • A Java 2 Standard Edition runtime environment
  • The Jakarta Commons HttpClient package.
  • The Apache Axis 1.2 Beta Web Services package.

Java 2 Standard Edition (1.4.x)
You can use any version of Java that is compatible with Apache AXIS 1.2 Beta. The sample code in this article was generated using J2SE 1.4.2, however other Java 2 Standard Edition versions should work with only minor modifications. You can get the J2SE runtime from Sun.

Jakarta Commons HttpClient
The Jakarta Commons HttpClient is a small package containing HTTP client that properly performs digest authentication. You need this package in order to configure Axis 1.2 properly. You can download Commons HttpClient here.

Apache Axis (1.2 Beta)
Apache Axis is one of the standard Java APIs for Web Services. You can download Axis 1.2 Beta here. Axis is also built into many modern Java development environments. Although you can try to use Axis 1.1, most people encounter an error related to the way in which Axis 1.1 handles authentication. Therefore, you are better off using Axis 1.2, even though it is still officially in Beta form.

Configuring Axis for Digest Authentication
One of the drawbacks to Axis is that it doesn't currently support digest authentication, which is used by the MapPoint Web Service. In order to make Axis authenticate properly, you have to configure Axis to use digest authentication for the MapPoint Web Service calls. The difference between basic and digest authentication is that basic authentication passes the username and password in clear text, whereas digest authentication uses one of several different hash schemes to create a unique (one way encrypted) string sequence combining the two values. Digest authentication is much more secure as the password is never sent in a recoverable form.

To overcome this limitation in the AXIS implementation, you need to reference the CommonsHttpSender class, which is part of the Commons-HttpClient jar file. Fortunately, if you have the packages installed properly, all you need to do is to create a descriptor that tells Axis to use CommonsHttpSender for all Web Services that use HTTP or HTTPS as the transport layer:

The descriptor is an XML file called client-config.wsdd, and must be placed in your classpath. The file should contain the following XML:


<?xml version="1.0" encoding="UTF-8"?> <deployment name="defaultClientConfig" xmlns="http://xml.apache.org/axis/wsdd/" xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"> <transport name="http" pivot="java:org.apache.axis.transport.http.CommonsHTTPSender" /> <transport name="https" pivot="java:org.apache.axis.transport.http.CommonsHTTPSender"/> <transport name="local" pivot="java:org.apache.axis.transport.local.LocalSender"/> </deployment>


Listing 1: Client-config.wsdd

Put the client-config.wsdd descriptor in your classpath and Axis will automatically read the descriptor and redirect HTTP requests to the CommonsHttpSender class built into the Commons-HttpClient package. The CommonsHttpSender class can properly handle the form of digest authentication used by the Microsoft Customer Data Service Website.

If you omit this step, you will encounter numerous authentication errors when you try to use the Customer Data Service Web service.

Formatting the Data
Both the Customer Data Service and the Customer Service Site are fairly flexible in terms of the format of your location data. However, you do have to follow certain specific rules in terms of headers, data types and required columns. For complete details on acceptable file formats, please see the MapPoint SDK or http://msdn.microsoft.com/library/en-us/mappointsdk/HTML/mpn35FormattingDataSources.asp.

The sample data attached to this article follows a very simple comma separated file format. You can also submit data as an XML document, or as the output of an Access database.

Required Columns
Regardless of how you format your data, you need to include a minimum of three columns:

  • EntityID—The EntityID must be unique within a world. That is, for a specific data source loaded as a specific entity type (e.g. offices), within a specific environment (e.g. staging), each EntityID must be unique. You can have duplicate ID values in staging and production, or in two different entity types (offices and stores). The EntityID can be any data type, however a long integer is most common
  • Latitude and Longitude—You must include Latitude and Longitude columns in your data file. If you leave these fields blank, then MapPoint will geocode your entry. However, if you want to bypass geocoding, you can enter data into the latitude and longitude fields.
In addition to the required fields, you will almost always want to include one or more of the address fields: AddressLine, CountryRegion, PrimaryCity, SecondaryCity, Subdivision, and/or PostalCode.

You can also add additional searchable columns for information that is specific to your data source. For example, you could add a field indicating whether a particular store can ship products directly to customers.

XML Format
In an XML file, you must start by defining a complex data type using XML Schema. The data type defines the fields you wish to upload and their data types.


<xsd:element name="MapPoint"> <xsd:complexType> <xsd:sequence> <xsd:element od:jetType="double" od:sqlSType="float" minOccurs="0" name="Latitude" type="xsd:double" /> <xsd:element od:jetType="double" od:sqlSType="float" minOccurs="0" name="Longitude" type="xsd:double" /> <xsd:element od:jetType="longinteger" od:sqlSType="bigint" minOccurs="0" name="EntityID" type="xsd:long" /> <!--file clipped for brevity --> </xsd:sequence> </xsd:element> </xsd:complexType> <dataroot> <MapPoint> <Latitude></Latitude> <Longitude></Longitude> <EntityID>1</EntityID> </MapPoint> <!--file clipped for brevity --> </dataroot>


Listing 2: An XML Data File Fragment

Naturally, a typical XML data file contains a much larger sequence of elements and many more rows of actual data.

Flat File Format
In a flat file, the first row of data contains the headers. You can optionally specify the data type in parenthesis after the column name. Acceptable data types include: long, double, Boolean, string, info and keyword. You can use commas, tabs or pipe characters (|) as delimiters in the file.


Latitude(double) Longitude(double) EntityID(long) LocationName(string) ,,1,Canada Office


Listing 3: A Flat Data File Fragment

The sample file included with the code represents a more typical flat file containing actual address information.

Building the Java Class
Once you have your accounts set up, and have a data file to upload, you can call the Customer Data Service to perform the file upload and geocoding. The actual upload process involves four steps:

  1. Get a Job ID—The Job ID is a unique string which identifies a particular upload job. You'll use the Job ID as an identifier in all of your Web Service calls.
  2. Chunk and upload the data—Depending on how much data you are uploading, you may need to make multiple Web Service calls to meet the size limitations. You will have to decide how large you want the data chunks to be and how many Web Service calls you need to make.
  3. Start the geocoding—Once you have uploaded the data, you need to tell the Customer Service Site that the job is ready for geocoding. The geocoding process may take seconds, minutes or hours depending on the amount and quality of your data. The MapPoint Customer Service Site officially commits to processing the file within 24 hours, however even the largest files usually process within a few hours.
  4. Poll for completion—The geocoding process is asynchronous. That is, once you start the process, the customer service site will complete the job on its own schedule. You can use another Web Service call to poll for job status.
However, before you can complete any of these steps, you need to generate a set of proxy classes based on the Customer Data Service WSDL description.

Remember that you can get the working source code for this article.

Create the Proxy Classes
The easiest way to create the Customer Data Service proxy classes is to use the WSDL2Java program that comes with the Apache Axis Web Service package. Ordinarily, you could direct WSDL2Java to the online WSDL. However, the WSDL description for the Customer Data Service is protected by HTTPS and your Customer Service Site credentials. Therefore, you have to access the WSDL file manually and save it before you can run WSDL2Java.

To create the proxy classes:
  1. Open a Web browser and navigate to https://mappoint-css.partners.extranet.microsoft.com/CustomerData-30/CustomerDataService.asmx?wsdl
  2. When prompted for credentials, enter your Customer Service Site user name and password. Note that, unlike the main CSS portal, you should not preface your user name with the "partners" domain. In fact, if you try to use "partners/username" you will encounter an authentication error.
  3. Save the WSDL to your local drive (e.g. c:\temp\CustomerDataService.wsdl).
  4. Change to the directory where you have stored the WSDL file (e.g. c:\temp)
  5. Run WSDL2Java with the following command line: java org.apache.axis.wsdl.WSDL2Java CustomerDataService.wsdl
  6. Compile the resulting Java code.
WSDL2Java will create a set of nested proxy classes in a directory called /net/mappoint/s/mappoint_30 (e.g. c:\temp\net\mappoint\s\mappoint_30). If you open this directory, you should see the following classes:
  • CustomerDataService—The CustomerDataService interface binds the Web Service to the necessary Axis support class.
  • CustomerDataServiceLocator—The locator class provides all of the pieces necessary to connect to the Web Service and create an instance of the CustomerDataServiceSoapStub class.
  • CustomerDataServiceSoap—This interface defines the four methods available on the Customer Data Service: startUpload(), uploadData(), finishUpload() and getJobState().
  • CustomerDataServiceSoapStub—The stub class contains the actual Web Service calls necessary to implement the CustomerDataServiceSoap interface. You will use this class as your primary connection to the Customer Data Service.
  • GeocodingLevel—The GeocodingLevel class is a static enumeration containing the possible geocoding levels: Street, Postal Code, City, Subdivision and Country/Region.
  • JobStateJobState is another static enumeration containing the various status values for an upload job.
  • LocationDataEnvironment—This class is another static enumeration containing the possible values for the location data: Staging or Service.
  • UploadSpecification—The UploadSpecification class is a data transfer object that defines the upload job you wish to perform.

If you want, you can compress the proxy classes into a JAR file; however, that is not necessary.

A Note on Proxy Classes
If you ever switch versions of Axis or of the J2SE runtime, you will need to regenerate your proxy files. If you don't regenerate your proxy files (by deleting the old classes, running WSDL2Java, and then recompiling the output), you will encounter numerous message formatting errors.

Connect to the Service
In order to perform any of the Web Service operations, you must first create a connection to the server. Using the code generated by AXIS, connecting to the server is as simple as using the locator class to generate an instance of CustomerDataServiceSoap:


System.err.println("Finding Service..."); CustomerDataServiceSoap uploadService = new CustomerDataServiceLocator().getCustomerDataServiceSoap(new URL(cssURL)); ((CustomerDataServiceSoapStub) uploadService).setUsername(user); ((CustomerDataServiceSoapStub) uploadService).setPassword(pwd);


Listing 4: Connecting to the service

In Listing 4, the cssURL parameter refers to the URL for the Customer Data Service which is "https://mappoint-css.partners.extranet.microsoft.com/CustomerData-30/CustomerDataService.asmx". The username and password refer to your Customer Service Site credentials. Note that the user name should not be prefaced with the "partners" domain. You need to use the same user name and credentials you used to access the WSDL document.

Get an Upload Job ID
Once you have connected to the service, the next task is to create an upload job ID. The job ID will act as your unique key for a particular data upload process.

The Upload Specification
Before you create a Job ID, you have to create an UploadSpecification.


UploadSpecification spec = new UploadSpecification(); spec.setDataSourceName(dsName); //e.g. Infusion.12345.Test spec.setEntityTypeName(entity); //e.g. Offices //Change to LocationDataEnvironment.Production for prod data spec.setEnvironment(LocationDataEnvironment.Staging); //Change to Street, City, PostalCode, Subdivision, CountryRegion for max geocoding level spec.setMaximumGeocodingLevel(GeocodingLevel.Street); spec.setRejectAmbiguousGeocodes(true);


Listing 5: Creating an Upload Specification

The upload specification defines five values:
  • Data Source Name—The data source name will be the name of your custom data source (E.g. Infusion.12345.Test). Data source names follow a three part format that includes:
    1. An arbitrary source (e.g. Infusion)—The source should usually be the name of your company or application. For example, Axicom, MapPoint and NavTech are the built in data sources.
    2. Your MapPoint Web Service account ID (e.g. 12345)—The second part of the data source name must always be your five digit account id. MapPoint uses this part of the data source name to limit access to your particular Web Service account.
    3. An arbitrary string (e.g. Test)—The third component is an arbitrary string that is usually tied to a geographic region. However, you can use any value you wish.
  • Entity Type Name—The entity type is an arbitrary classification. You might choose "office" or "restaurant" or "dealership" as an entity type representative of your data. When you access the data using the MapPoint Web Service API, you will need to know both the data source and the entity name.
  • Environment—You can use the LocationDataEnvironment enumeration to indicate whether your data should be uploaded to the production or staging environment.
  • Geocoding Level—You can use the GeocodingLevel enumeration to indicate the maximum geocoding level for an upload. For example, if you set this value to City, then any address that cannot be resolved at an address or postal code level will be resolved at the city level. If the address cannot be resolved at the city level, then the address will not be geocoded.
  • Reject Ambiguous Geocodes—If you set this value to true, then addresses that return more than one possible match will not be geocoded. If the value is false, then ambiguous geocodes will be mapped to the first match in the list of possible matches. You may want to adjust this value depending on how accurate your address data is. If you find you have many ambiguous addresses, you may want to individually encode each address using the MapPoint Web Service API. You can then take the resulting latitude and longitude, put them in your upload data file, and the Customer Data Service will automatically skip geocoding those addresses and store the attitude and longitude from the data file.

Generating the Job ID
Creating a Job ID is then as simple as passing your upload specification into the StartUpload() method:


String jobId = ((CustomerDataServiceSoapStub)uploadService).startUpload(spec);


Listing 6: Generating a Job ID

Note that the Job ID is a string value. You won't ever need to know what the actual value is, however it will always look like a GUID value.

Chunk and Upload the Data
Once you've got a Job ID, you can start uploading the data. The uploadData() method accepts three parameters, the Job ID, a Byte array of data, and a long integer indicating the total number of bytes uploaded so far.

In some cases, you can simply load your data file into a byte array and upload the entire file at once. However, if your file is bigger than one megabyte, or you are worried about the length of time required for such a large Web Service call, you can upload smaller chunks.


//Upload the file int chunkSize = 10000; //max is 1MB (1000000) File dataFile = new File(pathToFile); if (!dataFile.isFile()) { System.err.println("Not a file!"); } //Create an Input Stream to read the file as a byte array InputStream dataBytes = new FileInputStream(dataFile); long fileLength = dataFile.length(); // Create the byte array to hold the data byte[] data; // Read in the bytes long totalBytes = 0; //must be a long to handle files over 1 MB! int numRead = 0; // can be an int because we're limited to chunks less than 1000000 int numToRead = 0; while (totalBytes < fileLength) { numToRead = (int)(fileLength - totalBytes); if (numToRead > chunkSize) { numToRead = chunkSize; } data = new byte[(int)(numToRead)]; numRead=dataBytes.read(data); totalBytes = ((CustomerDataServiceSoapStub)uploadService).uploadData( jobId, data, totalBytes); } // Close the input stream dataBytes.close();


Listing 7: Chunking and Uploading the Data

Note that the while loop performs two main tasks: first it loads a chunk of data from our InputStream; second, it calls uploadData() to upload the chunk of data. We also have to keep careful track of the total number of bytes we've uploaded for a particular job. The byte total is necessary for the next step.

Start the Geocoding
Once the data has been successfully uploaded, we need to kick off the geocoding process. To start the geocoding, we have to call the finishUpload() method, passing in the Job ID and the total number of bytes we've uploaded in the current job. The byte check is necessary so that the MapPoint Server can ensure data integrity.


((CustomerDataServiceSoapStub)uploadService).finishUpload(jobId, totalBytes);


Listing 8: Starting the Geocoding process

At this point, our data will be placed on the queue for geocoding and loading into a custom data source. You can use the Customer Service Site to check on the status of the job.

Poll for Completion
Geocoding occurs asynchronously on the MapPoint server. Therefore, we have no control over exactly when a job will start or when it is finished. Although the MapPoint server tries to perform as fast as possible, certain factors may slow down the process. For example, if you try to upload a data source during peak access hours, the geocoding may be delayed. As mentioned previously, the MapPoint Customer Data Site guarantees geocoding within 24 hours of data submission. In most cases, geocoding is much faster, although it can take several hours.

If you want to find out the status of your geocoding, and whether your custom data source is live, you can either reuse the Customer Service Site or poll the Customer Data Service using the getJobState() method:


//Wait for completion int waitInterval = 10; //polling interval in seconds boolean notDone = true; while (notDone) { JobState js = ((CustomerDataServiceSoapStub)uploadService).getJobState(jobId); if (js == JobState.Loading) { System.err.println("Job is Loading"); } else if (js == JobState.Pending) { System.err.println("Job is Pending"); } else if (js == JobState.InProcess) { System.err.println("Job is In Process"); } else if (js == JobState.CompletedSuccess) { System.err.println("Job was completed successfully"); notDone = false; } else if (js == JobState.CompletedPartialSuccess) { System.err.println("Job was partially successful."); notDone = false; } else if (js == JobState.CompletedInvalid) { System.err.println("Job was invalid"); notDone = false; } else if (js == JobState.CompletedFailure) { System.err.println("Job failed to complete"); notDone = false; } else if (js == JobState.Expired) { System.err.println("Job timed out"); notDone = false; } Thread.sleep(waitInterval * 1000); }


Listing 9: Polling for job status

The returned status is an instance of the JobState enumeration.

Evaluating Status
If your job returns any status except CompletedSuccess, then an error occurred somewhere in the process. The various error states are:

  • Loading—You should never actually see the Loading status because you will have finished loading your data before polling on the Job ID.
  • Expired—You should never see the Expired state because it is only used when you've created a Job ID and haven't uploaded any data for 25 minutes. If you see this status, you may have failed to call the finishUpload() method, or your uploadData() calls may have failed.
  • Pending—You will see the Pending status until the job has actually started. This status indicates that your job is in the queue for the geocoding process. Depending on the current server load, you may see this status for several seconds or several minutes after calling finishUpload().
  • InProcess— Once the geocoding process has started to work on your data, you will see the InProcess status. You will see this status, intermittently with Pending, until your entire data set has been geocoded.
  • CompletedSuccess—If your entire data file was successfully geocoded, you will see a status of CompletedSuccess. Any other completed status indicates partial or complete failure.
  • CompletedPartialSuccess—If some of your records could not be geocoded, you will see the CompletedPartialSuccess status. In order to find out which records failed, you need to go to the Customer Service Site and look at the recent jobs. Unfortunately, the Customer Data Service does not provide a Web Service to access failed records.
  • CompletedInvalid—If your data file was corrupt or invalid, you will see the CompletedInvalid status. In most cases, this status is the result of a bad file format or an invalid character set.
  • CompletedFailure—If the geocoding failed due to any other error or exception, you will see the CompletedFailure status. If you encounter this status, you should make sure the Customer Service Site is active and then retry your upload process.
In the vast majority of cases, you will see a smooth transition from Pending to InProcess to CompletedSuccess or CompletedPartialSuccess. Once again, if you have a partial success, you need to go to the Customer Service Site to find out which records were invalid.

A Note on HTTPS Certificates
When you first attempt to run a Java client against the Customer Data Service, you may encounter an exception like "javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: No trusted certificate." This error usually occurs because Java doesn't recognize the HTTPS certificate Microsoft is using on the Customer Service Site. Microsoft uses an intermediate certificate built off of the primary Microsoft certificate which was issued by Thwate. Although most browsers have no trouble with intermediate certificates, Java won't recognize the validity of intermediate certificates.

In order to fix this problem, you need to download the certificate from the Customer Service Site and put it in the cacerts keystore for your Java runtime.

Download the Microsoft Certificate
The actual process for downloading the certificate depends on which type of Web browser you have available. These instructions are for Internet Explorer (5.5 or higher):

  1. Open Internet Explorer.
  2. Navigate to the CSS site and provide your credentials. This will make sure your browser recognizes the certificate.
  3. Go to Tools->Options->Content and click on Certificates.
  4. Select Intermediate Certification Authorities.
  5. Select Microsoft Secure Server Authority. There may be two certificates by this name. Repeat steps 5-7 for each one.
  6. Export the certificate to X.509 binary format as msft_css.cer. If you see a second certificate, export it and name it msft_css2.cer.
  7. Copy the .cer file(s) to your production server.

Register the Certificate
Java has an internal keystore for "gold standard" certificates. In a default installation, the keystore contains all known class 1, 2 and 3 certificates from Thwate and Verisign. You can add your own certificates to the keystore by using the keytool program.

  1. Change to the directory where you stored your downloaded certificates.
  2. Run the following command for the first certificate. You will need to change the path to the JRE cacerts file for your system.


  3. C:\Projects\MapPointSupport\java>keytool -import -alias MicrosoftMPCSS -file msft_css.cer -keystore c:\java\j2sdk1.4.2_05\jre\lib\security\cacerts


    Listing 10: Importing a certificate
  4. You will be prompted for a password. By default, the cacerts keystore has a password of "changeit"; however your system administrator may have change the password to something more secure.
  5. Repeat steps 2 and 3 for the second certificate (if you saw one). You will need to change the alias and the file values to match your second certificate
The keytool command will put the Microsoft Customer Service Site certificate into the keystore. Whenever Java encounters a site that is protected by the Microsoft Secure Server Authority certificate, Java will compare the site's certificate with the one you have registered as valid in the keystore. Once you have imported the certificate, your Web Service calls will no longer encounter the SSLHandshakeException for the Customer Data Service.

Additional Certificate Issues
Some versions of the J2SE environment shipped with expired root level certificates. If you are encountering an error that looks like:
   Publisher authenticity verified by: "Thwate"
   The security certificate was issued by a company that is trusted
   The security certificate has expired or is not yet valid

Then you should check out Sun's Alert Notification 57436. The alert notification describes the symptoms, the affected Java versions and the solution.

A Note on Working with Proxies
If you are trying to access the Customer Data Service through a proxy, you will need to add a few settings. Specifically, you will have to create two environment variables to identify the proxy and host:


System.setProperty("http.proxyHost",proxyServerAsString); System.setProperty("http.proxyPort",proxyPortAsString);


Listing 11: Setting up a Proxy

As long as you set these properties before trying to connect to the Web Service, you should have no problems.

Conclusion

Thanks to the Customer Service Site and the Customer Data Service, you can create and maintain your own MapPoint Data Sources. By adding custom data sources, you can take advantage of MapPoint's ability to geocode data, calculate distances, generate routes and provide maps for your locations. With the combination of MapPoint Web Service and the MapPoint Customer Data Service, you can build complete store locator style functionality without having to manually geocode, map, or store any local data.



Rob McGovern is Senior Project Manager with Infusion Development, which in a joint venture with Random House Trade Paperbacks produces CodeNotes´┐Ż, a new concept in computer-book publishing. The CodeNotes book series was designed for the software developer who needs to come up to speed quickly on a new language or technology. Infusion Development Corporation offers quality software development services, developer training and consulting services, with a focus on emerging and established Windows and UNIX software development technologies. They are a Microsoft Certified Solutions Provider, TIBCO Alliance Partner and Authorized Learning Partner (TALP), and Sun Java Partner.
Comment and Contribute

 

 

 

 

 


(Maximum characters: 1200). You have 1200 characters left.

 

 

Sitemap
Thanks for your registration, follow us on our social networks to keep up-to-date