Java tutorial
/* * Copyright (C) 2007 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.location; import android.content.Context; import android.location.Address; import android.os.RemoteException; import android.os.IBinder; import android.os.ServiceManager; import android.util.Log; import java.io.IOException; import java.util.Locale; import java.util.ArrayList; import java.util.List; /** * A class for handling geocoding and reverse geocoding. Geocoding is * the process of transforming a street address or other description * of a location into a (latitude, longitude) coordinate. Reverse * geocoding is the process of transforming a (latitude, longitude) * coordinate into a (partial) address. The amount of detail in a * reverse geocoded location description may vary, for example one * might contain the full street address of the closest building, while * another might contain only a city name and postal code. * * The Geocoder class requires a backend service that is not included in * the core android framework. The Geocoder query methods will return an * empty list if there no backend service in the platform. Use the * isPresent() method to determine whether a Geocoder implementation * exists. */ public final class Geocoder { private static final String TAG = "Geocoder"; private GeocoderParams mParams; private ILocationManager mService; /** * Returns true if the Geocoder methods getFromLocation and * getFromLocationName are implemented. Lack of network * connectivity may still cause these methods to return null or * empty lists. */ public static boolean isPresent() { IBinder b = ServiceManager.getService(Context.LOCATION_SERVICE); ILocationManager lm = ILocationManager.Stub.asInterface(b); try { return lm.geocoderIsPresent(); } catch (RemoteException e) { Log.e(TAG, "isPresent: got RemoteException", e); return false; } } /** * Constructs a Geocoder whose responses will be localized for the * given Locale. * * @param context the Context of the calling Activity * @param locale the desired Locale for the query results * * @throws NullPointerException if Locale is null */ public Geocoder(Context context, Locale locale) { if (locale == null) { throw new NullPointerException("locale == null"); } mParams = new GeocoderParams(context, locale); IBinder b = ServiceManager.getService(Context.LOCATION_SERVICE); mService = ILocationManager.Stub.asInterface(b); } /** * Constructs a Geocoder whose responses will be localized for the * default system Locale. * * @param context the Context of the calling Activity */ public Geocoder(Context context) { this(context, Locale.getDefault()); } /** * Returns an array of Addresses that are known to describe the * area immediately surrounding the given latitude and longitude. * The returned addresses will be localized for the locale * provided to this class's constructor. * * <p> The returned values may be obtained by means of a network lookup. * The results are a best guess and are not guaranteed to be meaningful or * correct. It may be useful to call this method from a thread separate from your * primary UI thread. * * @param latitude the latitude a point for the search * @param longitude the longitude a point for the search * @param maxResults max number of addresses to return. Smaller numbers (1 to 5) are recommended * * @return a list of Address objects. Returns null or empty list if no matches were * found or there is no backend service available. * * @throws IllegalArgumentException if latitude is * less than -90 or greater than 90 * @throws IllegalArgumentException if longitude is * less than -180 or greater than 180 * @throws IOException if the network is unavailable or any other * I/O problem occurs */ public List<Address> getFromLocation(double latitude, double longitude, int maxResults) throws IOException { if (latitude < -90.0 || latitude > 90.0) { throw new IllegalArgumentException("latitude == " + latitude); } if (longitude < -180.0 || longitude > 180.0) { throw new IllegalArgumentException("longitude == " + longitude); } try { List<Address> results = new ArrayList<Address>(); String ex = mService.getFromLocation(latitude, longitude, maxResults, mParams, results); if (ex != null) { throw new IOException(ex); } else { return results; } } catch (RemoteException e) { Log.e(TAG, "getFromLocation: got RemoteException", e); return null; } } /** * Returns an array of Addresses that are known to describe the * named location, which may be a place name such as "Dalvik, * Iceland", an address such as "1600 Amphitheatre Parkway, * Mountain View, CA", an airport code such as "SFO", etc.. The * returned addresses will be localized for the locale provided to * this class's constructor. * * <p> The query will block and returned values will be obtained by means of a network lookup. * The results are a best guess and are not guaranteed to be meaningful or * correct. It may be useful to call this method from a thread separate from your * primary UI thread. * * @param locationName a user-supplied description of a location * @param maxResults max number of results to return. Smaller numbers (1 to 5) are recommended * * @return a list of Address objects. Returns null or empty list if no matches were * found or there is no backend service available. * * @throws IllegalArgumentException if locationName is null * @throws IOException if the network is unavailable or any other * I/O problem occurs */ public List<Address> getFromLocationName(String locationName, int maxResults) throws IOException { if (locationName == null) { throw new IllegalArgumentException("locationName == null"); } try { List<Address> results = new ArrayList<Address>(); String ex = mService.getFromLocationName(locationName, 0, 0, 0, 0, maxResults, mParams, results); if (ex != null) { throw new IOException(ex); } else { return results; } } catch (RemoteException e) { Log.e(TAG, "getFromLocationName: got RemoteException", e); return null; } } /** * Returns an array of Addresses that are known to describe the * named location, which may be a place name such as "Dalvik, * Iceland", an address such as "1600 Amphitheatre Parkway, * Mountain View, CA", an airport code such as "SFO", etc.. The * returned addresses will be localized for the locale provided to * this class's constructor. * * <p> You may specify a bounding box for the search results by including * the Latitude and Longitude of the Lower Left point and Upper Right * point of the box. * * <p> The query will block and returned values will be obtained by means of a network lookup. * The results are a best guess and are not guaranteed to be meaningful or * correct. It may be useful to call this method from a thread separate from your * primary UI thread. * * @param locationName a user-supplied description of a location * @param maxResults max number of addresses to return. Smaller numbers (1 to 5) are recommended * @param lowerLeftLatitude the latitude of the lower left corner of the bounding box * @param lowerLeftLongitude the longitude of the lower left corner of the bounding box * @param upperRightLatitude the latitude of the upper right corner of the bounding box * @param upperRightLongitude the longitude of the upper right corner of the bounding box * * @return a list of Address objects. Returns null or empty list if no matches were * found or there is no backend service available. * * @throws IllegalArgumentException if locationName is null * @throws IllegalArgumentException if any latitude is * less than -90 or greater than 90 * @throws IllegalArgumentException if any longitude is * less than -180 or greater than 180 * @throws IOException if the network is unavailable or any other * I/O problem occurs */ public List<Address> getFromLocationName(String locationName, int maxResults, double lowerLeftLatitude, double lowerLeftLongitude, double upperRightLatitude, double upperRightLongitude) throws IOException { if (locationName == null) { throw new IllegalArgumentException("locationName == null"); } if (lowerLeftLatitude < -90.0 || lowerLeftLatitude > 90.0) { throw new IllegalArgumentException("lowerLeftLatitude == " + lowerLeftLatitude); } if (lowerLeftLongitude < -180.0 || lowerLeftLongitude > 180.0) { throw new IllegalArgumentException("lowerLeftLongitude == " + lowerLeftLongitude); } if (upperRightLatitude < -90.0 || upperRightLatitude > 90.0) { throw new IllegalArgumentException("upperRightLatitude == " + upperRightLatitude); } if (upperRightLongitude < -180.0 || upperRightLongitude > 180.0) { throw new IllegalArgumentException("upperRightLongitude == " + upperRightLongitude); } try { ArrayList<Address> result = new ArrayList<Address>(); String ex = mService.getFromLocationName(locationName, lowerLeftLatitude, lowerLeftLongitude, upperRightLatitude, upperRightLongitude, maxResults, mParams, result); if (ex != null) { throw new IOException(ex); } else { return result; } } catch (RemoteException e) { Log.e(TAG, "getFromLocationName: got RemoteException", e); return null; } } }