您现在的位置：程式碼之家 >> 編程語言 > >> Java 程式設計 >> J2ME

J2ME 定位 API 範例實作 (二)：Utils、ConfigurationProvider 核心原始碼深度解析

編輯：J2ME

Utils.formatDouble() — 雙精度數值格式化工具

J2ME 無 String.format、DecimalFormat，需自行實作定點數截斷 (非四捨五入)：

public class Utils {
    public static String formatDouble(double value, int decimals) {
        String doubleStr = String.valueOf(value); // 可能含科學記號或逗號/句點
        int index = doubleStr.indexOf('.');
        if (index == -1) index = doubleStr.indexOf(','); // 部分地區設定
        if (index == -1) return doubleStr;               // 整數直接返回

        if (decimals == 0) return doubleStr.substring(0, index); // 只要整數部

        int len = index + decimals + 1; // +1 保留小數點
        if (len > doubleStr.length()) len = doubleStr.length();
        // 截斷後再轉回 double 再 toString，移除尾端多餘 0
        double d = Double.parseDouble(doubleStr.substring(0, len));
        return String.valueOf(d);
    }
}

用途：將 GPS 座標 (如 25.03396789) 格式化為「25.03397」顯示於 UI，避免科學記號或過長小數位。

ConfigurationProvider — Provider 搜尋核心邏輯 (單例模式)

完整原始碼重構 (含註解)

package com.nokia.example.location.tourist.model;

import javax.microedition.location.*;
import com.nokia.example.location.tourist.ui.ProviderQueryUI;

public class ConfigurationProvider {
    // ---- 單例 ----
    private static ConfigurationProvider INSTANCE = null;
    public static ConfigurationProvider getInstance() {
        if (INSTANCE == null) {
            if (isLocationApiSupported()) INSTANCE = new ConfigurationProvider();
            else INSTANCE = null;
        }
        return INSTANCE;
    }
    public static boolean isLocationApiSupported() {
        String v = System.getProperty("microedition.location.version");
        return (v != null && v.length() > 0);
    }

    // ---- 靜態 Criteria 陣列建構 (類別載入時執行) ----
    private static Criteria[] freeCriterias = null;
    private static String[] freeCriteriaNames = null;
    private static Criteria[] costCriterias = null;
    private static String[] costCriteriaNames = null;

    static {
        // --- 免費準則組 ---
        freeCriterias = new Criteria[2];
        freeCriteriaNames = new String[2];

        // 1. 高細節、不計費
        Criteria c1 = new Criteria();
        c1.setHorizontalAccuracy(25);           // 25 m
        c1.setVerticalAccuracy(25);
        c1.setPreferredResponseTime(Criteria.NO_REQUIREMENT);
        c1.setPreferredPowerConsumption(Criteria.POWER_USAGE_HIGH);
        c1.setCostAllowed(false);               // 關鍵
        c1.setSpeedAndCourseRequired(true);
        c1.setAltitudeRequired(true);
        c1.setAddressInfoRequired(true);
        freeCriterias[0] = c1;
        freeCriteriaNames[0] = "High details, cost not allowed";

        // 2. 低細節、省電、不計費
        Criteria c2 = new Criteria();
        c2.setHorizontalAccuracy(Criteria.NO_REQUIREMENT);
        c2.setVerticalAccuracy(Criteria.NO_REQUIREMENT);
        c2.setPreferredResponseTime(Criteria.NO_REQUIREMENT);
        c2.setPreferredPowerConsumption(Criteria.POWER_USAGE_HIGH);
        c2.setCostAllowed(false);
        c2.setSpeedAndCourseRequired(false);
        c2.setAltitudeRequired(false);
        c2.setAddressInfoRequired(false);
        freeCriterias[1] = c2;
        freeCriteriaNames[1] = "Low details and power consumption, cost not allowed";

        // --- 付費準則組 ---
        costCriterias = new Criteria[3];
        costCriteriaNames = new String[3];

        // 1. 高細節、允許計費
        Criteria c3 = new Criteria();
        c3.setHorizontalAccuracy(25);
        c3.setVerticalAccuracy(25);
        c3.setPreferredResponseTime(Criteria.NO_REQUIREMENT);
        c3.setPreferredPowerConsumption(Criteria.NO_REQUIREMENT);
        c3.setCostAllowed(true);
        c3.setSpeedAndCourseRequired(true);
        c3.setAltitudeRequired(true);
        c3.setAddressInfoRequired(true);
        costCriterias[0] = c3;
        costCriteriaNames[0] = "High details, cost allowed";

        // 2. 中等細節、允許計費
        Criteria c4 = new Criteria();
        c4.setHorizontalAccuracy(500);          // 500 m
        c4.setVerticalAccuracy(Criteria.NO_REQUIREMENT);
        c4.setPreferredResponseTime(Criteria.NO_REQUIREMENT);
        c4.setPreferredPowerConsumption(Criteria.NO_REQUIREMENT);
        c4.setCostAllowed(true);
        c4.setSpeedAndCourseRequired(true);
        c4.setAltitudeRequired(true);
        c4.setAddressInfoRequired(false);
        costCriterias[1] = c4;
        costCriteriaNames[1] = "Medium details, cost allowed";

        // 3. 最寬鬆 (預設值全 NO_REQUIREMENT，costAllowed=true)
        costCriterias[2] = null; // null 代表預設 Criteria
        costCriteriaNames[2] = "Least restrictive criteria";
    }

    // ---- 實例欄位 ----
    private ProviderQueryUI queryUI = null;
    private Criteria criteria = null;
    private LocationProvider provider = null;

    private ConfigurationProvider() {
        queryUI = new ProviderQueryUI(); // 建立詢問使用者的 UI
    }

    // ---- 核心搜尋邏輯 ----
    public void autoSearch(ProviderStatusListener listener) {
        try {
            // 階段 1：免費準則依序嘗試
            for (int i = 0; i < freeCriterias.length; i++) {
                criteria = freeCriterias[i];
                provider = LocationProvider.getInstance(criteria);
                if (provider != null) {
                    listener.providerSelectedEvent(); // 成功回呼
                    return;
                }
            }
            // 階段 2：詢問使用者是否接受付費
            if (queryUI.confirmCostProvider()) {
                for (int i = 0; i < costCriterias.length; i++) {
                    criteria = costCriterias[i];
                    provider = LocationProvider.getInstance(criteria);
                    if (provider != null) {
                        listener.providerSelectedEvent();
                        return;
                    }
                }
            }
            // 階段 3：完全失敗
            queryUI.showNoFreeServiceFound();
        } catch (LocationException le) {
            queryUI.showOutOfService(); // Provider 暫時不可用
        }
    }

    // ---- 存取器 ----
    public LocationProvider getSelectedProvider() { return provider; }

    // ---- Orientation 支援 ----
    public Orientation getOrientation() {
        try { return Orientation.getOrientation(); }
        catch (LocationException e) { return null; }
    }
    public boolean isOrientationSupported() {
        try { Orientation.getOrientation(); return true; }
        catch (LocationException e) { return false; }
    }
}

關鍵設計決策解析

決策點	做法	理由
靜態區塊建構 Criteria	類別載入時一次性建立陣列	避免每次搜尋重複 new 物件、節省 Heap、確保參數不可變
免費優先、付費次之	先跑 freeCriterias 迴圈，失敗再彈確認對話框跑 costCriterias	符合使用者期望：免費優先、明確同意才計費
null Criteria 代表預設值	costCriterias[2] = null	`LocationProvider.getInstance(null)` 使用實作預設準則，作為最後嘗試
單例模式	私有建構子 + static getInstance()	全程只需一組 Criteria/Provider 狀態，避免多實例衝突
Orientation 延遲初始化	`getOrientation()` 呼叫時才嘗試取得	無指南針裝置不拋例外、UI 可依 `isOrientationSupported()` 隱藏指南針功能

ProviderQueryUI — 使用者互動介面

confirmCostProvider()：顯示「找到付費定位服務，是否使用？」確認對話框，回傳 boolean。
showNoFreeServiceFound()：顯示「無免費定位服務」錯誤訊息。
showOutOfService()：顯示「定位服務暫時不可用」錯誤訊息。
showLocationProviderState()：顯示「正在搜尋定位服務…」等待畫面。

皆繼承 Form 或 Alert，採用 CommandListener 處理使用者按鍵。

ProviderStatusListener — 狀態回呼介面

public interface ProviderStatusListener {
    void providerSelectedEvent();       // 找到 Provider，可開始使用
    void firstLocationUpdateEvent();    // 首次位置更新到達，可顯示主 UI
    void providerStateChanged(int state); // Provider 狀態變更 (AVAILABLE/TEMPORARILY_UNAVAILABLE/OUT_OF_SERVICE)
}

TouristMIDlet 實作此介面，串聯搜尋 → Model 建立 → UI 顯示的完整生命週期。

編譯與執行提醒

需引用 javax.microedition.location API (JSR-179)，WTK 2.5.2+ 內建，或 Nokia S60 SDK 內建。
編譯時 -bootclasspath 必須包含 jsr179.jar (或 SDK 對應 jar)。
預驗證 (preverify) 必須通過，否則真機安裝失敗。
JAD 需宣告 MIDlet-Permissions: javax.microedition.location.Location (若需簽名信任域)。

下一步預告

下一篇將完整解析 TouristData (LocationListener/ProximityListener 實作)、ControlPoints (LandmarkStore CRUD)、TouristUI (主畫面繪製與指令處理)、CompassUI/PitchRollUI (方位/姿態視覺化) 等核心 UI 與 Model 互動細節。