com.nttdocomo.device.location
クラス Location

Object
  com.nttdocomo.device.location.Location

public class Location

extends Object

[iアプリオプションAPI]

測位結果を表します。 このオブジェクトには、緯度・経度・高度・測地系・水平方向の精度といった位置情報、 ならびに測位時刻が格納されています。

緯度や経度の正負の解釈は以下の通りです。

	正の角度	0	負の角度
緯度	北緯	赤道	南緯
経度	東経	本初子午線	西経

例えば、緯度として「-10度」が、経度として「120度」が取得された場合、 このインスタンスは南緯 10 度、東経 120 度の地点を表していることになります。

プログラマが 測位を実施すると、 測位結果が格納されたこのクラスのインスタンスが返却されます。

導入されたバージョン:

DoJa-3.0 (505iGPS)、DoJa-4.0LE、DoJa-5.0 (903i)

フィールドの概要

static int	ACCURACY_COARSE 「測位レベル 1」に対応する精度の最悪値 [m] です(=2147483647)。
static int	ACCURACY_FINE 「測位レベル 3」に対応する精度の最悪値 [m] です(=49)。
static int	ACCURACY_NORMAL 「測位レベル 2」に対応する精度の最悪値 [m] です(=299)。
static int	ACCURACY_UNKNOWN 精度が不明であることを表します(=-1)。
static int	ALTITUDE_UNKNOWN 高度が不明であることを表します(=0x80000000)。
static int	PREFIX_DIRECTION 緯度・経度を表す文字列の表記方法として、 先頭に N/S/W/E を指定することを表します(=0)。
static int	PREFIX_SIGN 緯度・経度を表す文字列の表記方法として、 先頭に (+)/- を指定することを表します(=1)。

コンストラクタの概要

Location(Degree latitude, Degree longitude)
緯度・経度を指定して、このオブジェクトを生成します。

Location(Degree latitude, Degree longitude, int altitude, int datum, long timestamp, int accuracy)
緯度・経度・高度、基づいている測地系、測位時刻、水平方向の精度を指定して、 このオブジェクトを生成します。

Location(String url)
位置情報 URL を指定して、このオブジェクトを生成します。

Location(String url, int altitude, long timestamp)
位置情報 URL、高度、測位時刻 を指定して、このオブジェクトを生成します。

Location(String latitude, String longitude, int altitude, int datum, long timestamp, int accuracy)
緯度・経度・高度、基づいている測地系、測位時刻、水平方向の精度を指定して、 このオブジェクトを生成します。

メソッドの概要

Degree	calculateAzimuth(Location dst) このオブジェクトに対応する位置から、 指定された目的地への方位角を計算します。
double	calculateDistance(Location dst) このオブジェクトに対応する位置と、指定された目的地との地表面の距離を計算します。
int	getAccuracy() 水平方向の精度を [m] 単位で取得します。
int	getAltitude() 高度を取得します。
int	getDatum() このオブジェクトの緯度・経度・高度が基づいている測地系を取得します。
String	getJointRFIURL() このオブジェクトに対応する位置情報 URL のクエリー文字列 (Joint RFI 形式) を取得します。
Degree	getLatitude() 緯度を取得します。
String	getLatitudeString(int prefix, int unit) 緯度の、指定された方位の接頭辞と単位における文字列表現を返します。
Degree	getLongitude() 経度を取得します。
String	getLongitudeString(int prefix, int unit) 経度の、指定された方位の接頭辞と単位における文字列表現を返します。
String	getPointOfInterestURL() 推奨されていません。 DoJa-4.0 以降では getJointRFIURL() を利用して下さい。
long	getTimestamp() 測位した時刻をミリ秒単位で取得します。
void	setAltitude(int altitude) 高度を設定します。
void	setLatitude(Degree latitude) 緯度を設定します。
void	setLongitude(Degree longitude) 経度を設定します。
Location	transform(int datum) このオブジェクトを、指定された測地系に変換した Location オブジェクトを取得します。

クラス Object から継承したメソッド

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

フィールドの詳細

ACCURACY_FINE

public static final int ACCURACY_FINE

「測位レベル 3」に対応する精度の最悪値 [m] です(=49)。

関連項目:

getAccuracy(), 定数フィールド値

ACCURACY_NORMAL

public static final int ACCURACY_NORMAL

「測位レベル 2」に対応する精度の最悪値 [m] です(=299)。

関連項目:

getAccuracy(), 定数フィールド値

ACCURACY_COARSE

public static final int ACCURACY_COARSE

「測位レベル 1」に対応する精度の最悪値 [m] です(=2147483647)。

関連項目:

getAccuracy(), 定数フィールド値

ACCURACY_UNKNOWN

public static final int ACCURACY_UNKNOWN

精度が不明であることを表します(=-1)。

関連項目:

getAccuracy(), 定数フィールド値

PREFIX_DIRECTION

public static final int PREFIX_DIRECTION

緯度・経度を表す文字列の表記方法として、 先頭に N/S/W/E を指定することを表します(=0)。

関連項目:

getLatitudeString(int, int), getLongitudeString(int, int), 定数フィールド値

PREFIX_SIGN

public static final int PREFIX_SIGN

緯度・経度を表す文字列の表記方法として、 先頭に (+)/- を指定することを表します(=1)。

関連項目:

getLatitudeString(int, int), getLongitudeString(int, int), 定数フィールド値

ALTITUDE_UNKNOWN

public static final int ALTITUDE_UNKNOWN

高度が不明であることを表します(=0x80000000)。

関連項目:

setAltitude(int), 定数フィールド値

コンストラクタの詳細

Location

public Location(Degree latitude,
                Degree longitude)

緯度・経度を指定して、このオブジェクトを生成します。 Location(latitude, longitude, ALTITUDE_UNKNOWN, LocationProvider.DATUM_WGS84, System.currentTimeMillis(), 0) を呼び出すことと等価です。

パラメータ:

latitude - 緯度を表す Degree オブジェクトを指定します。 表現する角度が、区間 [-90度, 90度] に含まれている必要があります。

longitude - 経度を表す Degree オブジェクトを指定します。 表現する角度が、区間 [-180度, 180度) に含まれている必要があります。

例外:

UnsupportedOperationException - 位置情報取得機能をサポートしていない場合に発生します。

NullPointerException - 引数 latitude または longitude に null を指定した場合に発生します。

IllegalArgumentException - 引数 latitude が表現する角度が、 区間 [-90度, 90度] に含まれていない場合に発生します。

IllegalArgumentException - 引数 longitude が表現する角度が、 区間 [-180度, 180度) に含まれていない場合に発生します。

Location

public Location(String url)

位置情報 URL を指定して、このオブジェクトを生成します。 Location(url, ALTITUDE_UNKNOWN, System.currentTimeMillis()) を呼び出すことと等価です。

パラメータ:

url - 位置情報 URL を指定します。クエリー文字列部分だけを指定しても、 ホスト名やプロトコルスキームを含めた完全な URL を指定しても構いません。

例外:

UnsupportedOperationException - 位置情報取得機能をサポートしていない場合に発生します。

NullPointerException - 引数 url に null を指定した場合に発生します。

IllegalArgumentException - 引数 url が、位置情報 URL (またはそのクエリー文字列) として解釈できない場合に発生します。

Location

public Location(Degree latitude,
                Degree longitude,
                int altitude,
                int datum,
                long timestamp,
                int accuracy)

緯度・経度・高度、基づいている測地系、測位時刻、水平方向の精度を指定して、 このオブジェクトを生成します。 なお、測位時刻、水平方向の精度を設定し直すメソッドは用意されていません。

パラメータ:

latitude - 緯度を表す Degree オブジェクトを指定します。 表現する角度が、区間 [-90度, 90度] に含まれている必要があります。

longitude - 経度を表す Degree オブジェクトを指定します。 表現する角度が、区間 [-180度, 180度) に含まれている必要があります。

altitude - 高度 [m] を指定します。 不明な場合には ALTITUDE_UNKNOWN を指定します。

datum - 引数で指定した緯度・経度 ・高度が基づいている測地系を指定します。 LocationProvider クラスで定義されている "DATUM_" から始まる定数を指定できます。

timestamp - 測位時刻を、 1970 年 1 月 1 日午前 0 時 (GMT) との差分で指定します。

accuracy - 水平方向の精度 [m] を指定します。 不明な場合は ACCURACY_UNKNOWN を、 1m 未満である場合には 0 を指定します。

例外:

UnsupportedOperationException - 位置情報取得機能をサポートしていない場合に発生します。

NullPointerException - 引数 latitude または longitude に null を指定した場合に発生します。

IllegalArgumentException - 引数 datum に不正な値を指定した場合に発生します。

IllegalArgumentException - 引数 accuracy に、-2 以下の値を指定した場合に発生します。

IllegalArgumentException - 引数 latitude が表現する角度が、 区間 [-90度, 90度] に含まれていない場合に発生します。

IllegalArgumentException - 引数 longitude が表現する角度が、 区間 [-180度, 180度) に含まれていない場合に発生します。

Location

public Location(String latitude,
                String longitude,
                int altitude,
                int datum,
                long timestamp,
                int accuracy)

緯度・経度・高度、基づいている測地系、測位時刻、水平方向の精度を指定して、 このオブジェクトを生成します。 なお、測位時刻、水平方向の精度を設定し直すメソッドは用意されていません。

このコンストラクタでは、緯度や経度に文字列を指定できます。 getLatitudeString(int, int)、 getLongitudeString(int, int) により定義されているフォーマットに従っていれば、 どの形式であっても正しく解釈されます。 特に、形式によって、正の角度を表す時に "+" を指定しなければならないものと、 "+" を指定できないものが混在していることに注意してください。

パラメータ:

latitude - 緯度を表す文字列を指定します。 表現する角度が、区間 [-90度, 90度] に含まれている必要があります。

longitude - 経度を表す文字列を指定します。 表現する角度が、区間 [-180度, 180度) に含まれている必要があります。

altitude - 高度 [m] を指定します。 不明な場合には ALTITUDE_UNKNOWN を指定します。

datum - 引数で指定した緯度・経度 ・高度が基づいている測地系を指定します。 LocationProvider クラスで定義されている "DATUM_" から始まる定数を指定できます。

timestamp - 測位時刻を、 1970 年 1 月 1 日午前 0 時 (GMT) との差分で指定します。

accuracy - 水平方向の精度 [m] を指定します。 不明な場合は ACCURACY_UNKNOWN を、 1m 未満である場合には 0 を指定します。

例外:

UnsupportedOperationException - 位置情報取得機能をサポートしていない場合に発生します。

NullPointerException - 引数 latitude または longitude に null を指定した場合に発生します。

IllegalArgumentException - 引数 datum に不正な値を指定した場合に発生します。

IllegalArgumentException - 引数 latitude や longitude に指定された文字列が、 不正なフォーマットである場合に発生します。

IllegalArgumentException - 引数 accuracy に、-2 以下の値を指定した場合に発生します。

IllegalArgumentException - 引数 latitude が表現する角度が、 区間 [-90度, 90度] に含まれていない場合に発生します。

IllegalArgumentException - 引数 longitude が表現する角度が、 区間 [-180度, 180度) に含まれていない場合に発生します。

Location

public Location(String url,
                int altitude,
                long timestamp)

位置情報 URL、高度、測位時刻 を指定して、このオブジェクトを生成します。

位置情報 URL のクエリー文字列としては、 以下のいずれかを指定することができます。

• PDC 端末で使用されているもの
• FOMA 端末で使用されているもの (FOMA 端末に限り指定することができます。)

それぞれのケースにおいて、 このオブジェクトの緯度・経度、測地系、精度(測位レベル)は、 指定された URL のクエリー文字列における以下のパラメータの値を基に設定されます。

PDC 端末で使用されている文字列を指定した場合:

pos(必須)、geo(必須)、 X-acc(オプション)

FOMA 端末で使用されている文字列を指定した場合:

lat(必須)、lon(必須)、 alt(オプション)、 geo(必須)、x-acc(オプション)

(いずれの場合においても、 精度については、X-acc・x-accの値が "3"、"2"、"1" の場合に、 それぞれ ACCURACY_FINE、 ACCURACY_NORMAL、 ACCURACY_COARSE が設定されます)。

なお、これらのパラメータの内、 「必須」と書かれているパラメータは必ず指定されていなければなりませんが、 「オプション」と書かれているものは指定されていなくても構いません。 「オプション」 のパラメータが指定されていなかった場合のデフォルト値は以下の通りです。

• X-acc・x-acc が指定されていない場合、 精度には ACCURACY_UNKNOWN が指定されたものとして解釈されます。
• [DoJa-4.0LE、DoJa-5.0 (903i) 以降] alt が指定されていない場合は、 高度として引数 altitude で指定された値が採用されます (PDC 端末で使用されているクエリー文字列を指定する場合には、 alt パラメータを含めることが出来ないため、常に引数 altitude で指定した値が高度として採用されることに注意して下さい)。

なお、指定されたクエリー文字列は、 pos パラメータが存在するものは PDC 端末で使用されているものとして、存在しないものは FOMA 端末で使用されているものとして、それぞれ解釈がなされます。 いずれの場合でも、 他の余分なパラメータが指定されていても構いません (そのようなパラメータは単に無視されます)。

パラメータ:

url - 位置情報 URLを指定します。クエリー文字列部分だけを指定しても、 ホスト名やプロトコルスキームを含めた完全な URL を指定しても構いません。

altitude - 高度 [m] のデフォルト値を指定します。 不明な場合には ALTITUDE_UNKNOWN を指定します。

timestamp - 測位時刻を、 1970 年 1 月 1 日午前 0 時 (GMT) との差分で指定します。

例外:

UnsupportedOperationException - 位置情報取得機能をサポートしていない場合に発生します。

NullPointerException - 引数 url に null を指定した場合に発生します。

IllegalArgumentException - 引数 url が、位置情報 URL (またはそのクエリー文字列) として解釈できない場合に発生します。

関連項目:

getPointOfInterestURL(), getJointRFIURL()

メソッドの詳細

getTimestamp

public long getTimestamp()

測位した時刻をミリ秒単位で取得します。

このオブジェクトが、LocationProvider.getLocation() により取得されたものである場合、取得できる時刻は、 測位結果を受け取った時点の端末時刻であり、 ミニマムスペックでは、その時の精度は1秒です。

戻り値:

ミリ秒で測定した、 測位時刻と 1970 年 1 月 1 日午前 0 時 (GMT) との差を返します。

getDatum

public int getDatum()

このオブジェクトの緯度・経度・高度が基づいている測地系を取得します。 返される値は、 LocationProvider クラスで定義されている "DATUM_" から始まる定数のいずれかです。

戻り値:

このオブジェクトが基づいている測地系を返します。

transform

public Location transform(int datum)

このオブジェクトを、指定された測地系に変換した Location オブジェクトを取得します。 このメソッド呼び出しによる副作用はありません。 計算時に用いられる緯度・経度･高度の値は DEGREE 単位です。

パラメータ:

datum - 変換したい測地系を指定します。 LocationProvider クラスで定義されている "DATUM_" から始まる定数を指定できます。

戻り値:

変換後の(引数 datum で指定された測地系に基づいている)位置情報を返します。 緯度・経度・高度・基づいている測地系以外の情報は、 このオブジェクトに格納されている情報と同じです。 また、引数 datum に getDatum() の戻り値と同じ値が指定された場合は、このオブジェクト自身 (this) が返されます。

例外:

IllegalArgumentException - 引数 datum に不正な値を指定した場合に発生します。

getLatitude

public Degree getLatitude()

緯度を取得します。

戻り値:

緯度を表す Degree オブジェクトを返します。 値域は [-90度, 90度] です。

setLatitude

public void setLatitude(Degree latitude)

緯度を設定します。

パラメータ:

latitude - 緯度を表す Degree オブジェクトを指定します。 表現する角度が、区間 [-90度, 90度] に含まれている必要があります。

例外:

NullPointerException - 引数 latitude に null を指定した場合に発生します。

IllegalArgumentException - 引数 latitude が表現する角度が、 区間 [-90度, 90度] に含まれていない場合に発生します。

getLatitudeString

public String getLatitudeString(int prefix,
                                int unit)

緯度の、指定された方位の接頭辞と単位における文字列表現を返します。 各引数の組み合わせにおける文字列表現のフォーマットは以下の通りです。

unit = UNIT_DEGREEの場合:

出力文字列 latstring は、文法規則

 latstring = sign num
 num = 緯度の絶対値の10進小数表記 [度] を小数点以下第6位まで表したもの。
       小数部は常に6桁で表現し、整数部は先頭には "0" をつけません。
       (C言語ライブラリ関数 printf の書式指定文字列 "%.6f" と同等)
 

に従います。

unit = UNIT_DMSの場合:

出力文字列 latstring は、文法規則

 latstring = sign degrees "." minutes "." seconds "." secfrac
 degrees = Integer.toString(Math.abs(getLatitude().getDegreePart())) の値
           (先頭に "0" は付けず、桁数は可変となります)
 minutes = Integer.toString(getLatitude().getMinutePart()) の値
           (1 桁の場合は、先頭に "0" を 1 つ付加します)
 seconds = Integer.toString(getLatitude().getCentisecondPart() / 100) の値
           (1 桁の場合は、先頭に "0" を 1 つ付加します)
 secfrac = Integer.toString(getLatitude().getCentisecondPart() % 100) の値
           (1 桁の場合は、先頭に "0" を 1 つ付加します)
 

に従います。

unit = UNIT_DMS_2の場合(FOMA 端末のみ指定が可能) :

出力文字列 latstring は、文法規則

 latstring = sign2 degrees "." minutes "." seconds
 degrees = Integer.toString(Math.abs(getLatitude().getDegreePart())) の値
           
           常に、整数部2桁で表現し、必要に応じて "0" を付加します。
           (C言語ライブラリ関数 printf の書式指定文字列 "%02d" と同等)
 minutes = Integer.toString(getLatitude().getMinutePart()) の値
           (1 桁の場合は、先頭に "0" を 1 つ付加します)
 seconds = getLatitude().getSecondPart() の値を、小数点以下第3位まで表したもの。
           常に、整数部は2桁、小数部は3桁で表現し、必要に応じて "0" を付加します。
           (C言語ライブラリ関数 printf の書式指定文字列 "%06.3f" と同等)
 

に従います。

ここで、sign、sign2 は

 sign = sign-except-plus
      | ""  ; 引数 prefix が PREFIX_SIGN で、角度が 0 か正の値の場合

 sign2 = sign-except-plus
      | "+"  ; 引数 prefix が PREFIX_SIGN で、角度が 0 か正の値の場合
 
 sign-except-plus =
        "N" ; 引数 prefix が PREFIX_DIRECTION で、角度が 0 か正の値の場合
      | "S" ; 引数 prefix が PREFIX_DIRECTION で、角度が負の値の場合
      | "-" ; 引数 prefix が PREFIX_SIGN で、角度が負の値の場合
 

です。

なお、引数 unit に指定する値によっては、 得られる文字列表現に、単位の変換による丸め誤差が含まれている場合があります。 詳細は Degree クラスの説明を参照してください。

パラメータ:

prefix - 方位の接頭辞の表記方法を指定します。 PREFIX_SIGN、 PREFIX_DIRECTION のいずれかの値を指定します。

unit - 単位を指定します。 LocationProvider.UNIT_DEGREE、 LocationProvider.UNIT_DMS、 LocationProvider.UNIT_DMS_2 のいずれかの値を指定します。

例外:

IllegalArgumentException - 引数 prefix に不正な値を指定した場合に発生します。

IllegalArgumentException - 引数 unit に不正な値を指定した場合に発生します。

getLongitude

public Degree getLongitude()

経度を取得します。

戻り値:

経度を表す Degree オブジェクトを返します。 値域は [-180度, 180度) です。

setLongitude

public void setLongitude(Degree longitude)

経度を設定します。

パラメータ:

longitude - 経度を表す Degree オブジェクトを指定します。 表現する角度が、区間 [-180度, 180度) に含まれている必要があります。

例外:

NullPointerException - 引数 longitude に null を指定した場合に発生します。

IllegalArgumentException - 引数 longitude が表現する角度が、 区間 [-180度, 180度) に含まれていない場合に発生します。

getLongitudeString

public String getLongitudeString(int prefix,
                                 int unit)

経度の、指定された方位の接頭辞と単位における文字列表現を返します。 各引数の組み合わせにおける文字列表現のフォーマットは以下の通りです

unit = UNIT_DEGREEの場合:

出力文字列 lonstring は、文法規則

 lonstring = sign num
 num = 経度の絶対値の10進小数表記 [度] を小数点以下第6位まで表したもの。
       小数部は常に6桁で表現し、整数部は先頭には "0" をつけません。
       (C言語ライブラリ関数 printf の書式指定文字列 "%.6f" と同等)
 

に従いますが、 丸め誤差などの原因により "180.000000" ("E180.000000") が得られた場合には、代わりに "-180.000000" ("W180.000000")を出力文字列とします。

unit = UNIT_DMSの場合:

出力文字列 lonstring は、文法規則

 lonstring = sign degrees "." minutes "." seconds "." secfrac
 degrees = Integer.toString(Math.abs(getLongitude().getDegreePart())) の値
           (先頭に "0" は付けず、桁数は可変となります)
 minutes = Integer.toString(getLongitude().getMinutePart()) の値
           (1 桁の場合は、先頭に "0" を 1 つ付加します)
 seconds = Integer.toString(getLongitude().getCentisecondPart() / 100) の値
           (1 桁の場合は、先頭に "0" を 1 つ付加します)
 secfrac = Integer.toString(getLongitude().getCentisecondPart() % 100) の値
           (1 桁の場合は、先頭に "0" を 1 つ付加します)
 

に従いますが、 丸め誤差などの原因により "180.00.00.00" ("E180.00.00.00") が得られた場合には、代わりに "-180.00.00.00" ("W180.00.00.00") を出力文字列とします。

unit = UNIT_DMS_2の場合(FOMA 端末のみ指定が可能) :

出力文字列 lonstring は、文法規則

 lonstring = sign2 degrees "." minutes "." seconds
 degrees = Integer.toString(Math.abs(getLongitude().getDegreePart())) の値
           
           常に、整数部3桁で表現し、必要に応じて "0" を付加します。
           (C言語ライブラリ関数 printf の書式指定文字列 "%03d" と同等)
 minutes = Integer.toString(getLongitude().getMinutePart()) の値
           (1 桁の場合は、先頭に "0" を 1 つ付加します)
 seconds = getLongitude().getSecondPart() の値を、小数点以下第3位まで表したもの。
           常に、整数部は2桁、小数部は3桁で表現し、必要に応じて "0" を付加します。
           (C言語ライブラリ関数 printf の書式指定文字列 "%06.3f" と同等)
 

に従いますが、 丸め誤差などの原因により "+180.00.00.000" ("E180.00.00.000") が得られた場合には、代わりに "-180.00.00.000" ("W180.00.00.000") を出力文字列とします。

ここで、sign、sign2 は

 sign = sign-except-plus
      | ""  ; 引数 prefix が PREFIX_SIGN で、角度が 0 か正の値の場合

 sign2 = sign-except-plus
      | "+"  ; 引数 prefix が PREFIX_SIGN で、角度が 0 か正の値の場合
 
 sign-except-plus =
        "E" ; 引数 prefix が PREFIX_DIRECTION で、角度が 0 か正の値の場合
      | "W" ; 引数 prefix が PREFIX_DIRECTION で、角度が負の値の場合
      | "-" ; 引数 prefix が PREFIX_SIGN で、角度が負の値の場合
 

です。

なお、引数 unit に指定する値によっては、 得られる文字列表現に、単位の変換による丸め誤差が含まれている場合があります。 詳細は Degree クラスの説明を参照してください。

パラメータ:

prefix - 方位の接頭辞の表記方法を指定します。 PREFIX_SIGN、 PREFIX_DIRECTION のいずれかの値を指定します。

unit - 単位を指定します。 LocationProvider.UNIT_DEGREE、 LocationProvider.UNIT_DMS、 LocationProvider.UNIT_DMS_2 のいずれかの値を指定します。

例外:

IllegalArgumentException - 引数 prefix に不正な値を指定した場合に発生します。

IllegalArgumentException - 引数 unit に不正な値を指定した場合に発生します。

getAltitude

public int getAltitude()

高度を取得します。

[DoJa-4.0LE 以前] 高度の測位はサポートされていません。
[DoJa-5.0 (903i) 以降] 高度の測位がサポートされているかどうかは機種依存です。

高度の測位がサポートされていない場合には、 LocationProvider インスタンスに対する getLocation().getAltitude() 呼び出しは、常に ALTITUDE_UNKNOWN を返します。 なお、コンストラクタや setAltitude(int) によって明示的に高度が指定されているインスタンスについては、 指定された高度の値をそのまま返します。

戻り値:

高度を返します。単位は [m] です。

setAltitude

public void setAltitude(int altitude)

高度を設定します。

パラメータ:

altitude - 高度 [m] を指定します。 不明な場合には ALTITUDE_UNKNOWN を指定します。

getAccuracy

public int getAccuracy()

水平方向の精度を [m] 単位で取得します。

現在の、 精度情報が「測位レベル」としてしか取得できない実装では、 ACCURACY_FINE、 ACCURACY_NORMAL、 ACCURACY_COARSE、 ACCURACY_UNKNOWN のいずれかしか返されません。 しかしながら、これらのフィールド値はそれぞれの 「測位レベル」における精度値(の最悪値)と一致しているため、 どちらの実装の場合でも同様な方法で精度の大小を比較することが可能です。

なお、コンストラクタによって明示的に水平方向の精度が指定されているインスタンスについては、 指定された水平方向の精度の値をそのまま返します。

戻り値:

水平方向の精度を返します。 単位は [m]です。 1m未満の場合には 0 が返ります。 精度が不明な場合には ACCURACY_UNKNOWN が返ります。

calculateDistance

public double calculateDistance(Location dst)

このオブジェクトに対応する位置と、指定された目的地との地表面の距離を計算します。 高度の情報は無視されます。

引数 dst とこのオブジェクトの測地系が異なる場合には、 引数 dst の測地系をこのオブジェクトの測地系に変換した上で、 距離の計算が行われます。 計算時に用いられる緯度･経度などの値は DEGREE 単位 (浮動小数点数表現)です。

距離の計算に利用されるアルゴリズムは「球面三角法」です。

パラメータ:

dst - 目的地を表す Location オブジェクトを指定します。

戻り値:

指定された目的地との地表面の距離 [m] を返します。

例外:

NullPointerException - 引数 dst に null を指定した場合に発生します。

導入されたバージョン:

DoJa-4.0LE、DoJa-5.0 (903i)

calculateAzimuth

public Degree calculateAzimuth(Location dst)

このオブジェクトに対応する位置から、 指定された目的地への方位角を計算します。

真北(true north)の方向を基準として、 そこから時計回りに指定された目的地の方向をなす角度を計算します。

引数 dst とこのオブジェクトの測地系が異なる場合には、 引数 dst の測地系をこのオブジェクトの測地系に変換した上で、 方位角の計算が行われます。 計算時に用いられる緯度･経度などの値は DEGREE 単位(浮動小数点数表現)です。

パラメータ:

dst - 目的地を表す Location オブジェクトを指定します。

戻り値:

この位置から指定された目的地への方位角を表す Degree オブジェクトを返します。値域は [0度, 360度) です。

例外:

NullPointerException - 引数 dst に null を指定した場合に発生します。

ArithmeticException - このオブジェクトが表す地点と、 引数 dst が表す地点が同一であった場合など、 方位角が計算できない場合に発生します。

導入されたバージョン:

DoJa-4.0LE、DoJa-5.0 (903i)

getPointOfInterestURL

public String getPointOfInterestURL()

推奨されていません。 DoJa-4.0 以降では getJointRFIURL() を利用して下さい。

このオブジェクトに対応する位置情報 URL のクエリー文字列 (iナビリンク形式(MOPA 形式)) を取得します。 URL とクエリー文字列の区切り文字である「?」は含まれません。

返却されるクエリー文字列のパラメータは、 pos、geo、X-acc の3種類で構成されています。

このオブジェクトが保持している精度が不明な場合は、 返される文字列に X-acc パラメータは含まれません。

このオブジェクトが Location(String, int, long) や Location(String) によって生成された場合、 オブジェクト生成時に指定したクエリー文字列と同じ文字列を取得できるとは限りません。 オブジェクトは内部的に DEGREE 単位(浮動小数点数表現) で値を保持するため、 その単位との変換による丸め誤差が含まれる可能性があります。

戻り値:

位置情報 URL (iナビリンク形式(MOPA 形式)) のクエリー文字列を返します。

getJointRFIURL

public String getJointRFIURL()

このオブジェクトに対応する位置情報 URL のクエリー文字列 (Joint RFI 形式) を取得します。 URL とクエリー文字列の区切り文字である「?」は含まれません。

返却されるクエリー文字列のパラメータは、 lat、lon、geo、 alt、x-acc の5種類で構成されており、 application/x-www-form-urlencoded によってエンコードされています。

このオブジェクトが保持している高度が不明な場合は、返される文字列に alt パラメータは含まれません。 同様に、精度が不明な場合は、 返される文字列に x-acc パラメータは含まれません。

このオブジェクトが Location(String, int, long) や Location(String) によって生成された場合、 オブジェクト生成時に指定したクエリー文字列と同じ文字列を取得できるとは限りません。 オブジェクトは内部的に DEGREE 単位(浮動小数点数表現) で値を保持するため、 その単位との変換による丸め誤差が含まれる可能性があります。

戻り値:

位置情報 URL (Joint RFI 形式) のクエリー文字列を返します。

導入されたバージョン:

DoJa-4.0LE、DoJa-5.0 (903i)