ApplicationUpdater  - AS3

Położenie pliku konfiguracyjnego, w którym określone są wartości właściwości delay i updateURL. Jeśli ta właściwość wskazuje na nieistniejący plik, wywołanie metody initialize() spowoduje wygenerowanie wyjątku Error.

Oto przykładowy plik konfiguracyjny:

 <?xml version="1.0" encoding="utf-8"?> 
         <configuration xmlns="http://ns.adobe.com/air/framework/update/configuration/1.0" >
           <url>app:/server/update.xml</url>
           <delay>1</delay>
        </configuration>

Zamiast ładować plik konfiguracyjny, można za pomocą kodu ActionScript przypisać wartości właściwościom delay i updateURL.

Powiązane elementy interfejsu API

Wewnętrzny stan obiektu Updater. Właściwość może przyjmować następujące wartości:

• "UNINITIALIZED" — obiekt Updater nie został zainicjowany.

• "INITIALIZING" — trwa inicjowanie obiektu Updater.

• "READY" — obiekt Updater został zainicjowany.

• "BEFORE_CHECKING" — obiekt Updater nie sprawdził jeszcze, czy istnieje plik deskryptora aktualizacji.

• "CHECKING" — obiekt Updater sprawdza, czy istnieje plik deskryptora aktualizacji.

• "AVAILABLE" — plik deskryptora aktualizacji jest dostępny.

• "DOWNLOADING" — obiekt Updater pobiera plik AIR.

• "DOWNLOADED" — obiekt Updater pobrał plik AIR.

• "INSTALLING" — obiekt Updater instaluje plik AIR.

• "PENDING_INSTALLING" — obiekt Updater jest zainicjowany i istnieją oczekujące aktualizacje.

Bieżąca wersja aplikacji. Wartość tej właściwości jest przypisywana podczas wywołania metody initialize(). Przypisana wartość jest równa wersji określonej w pliku deskryptora aplikacji.

Odstęp czasu (w dniach) między sprawdzeniami dostępności nowych aktualizacji.

Wartość 0 (domyślna) oznacza, że licznik czasu nie jest aktywny, a zatem dostępność aktualizacji nie jest regularnie sprawdzana. Wartość można określić za pośrednictwem tej właściwości lub w pliku konfiguracyjnym. Gdy wartość jest określona na oba sposoby, przyjmowana jest wartość przypisana właściwości.

Wartością domyślną jest 0.

Określa, czy jest to pierwsze uruchomienie po pomyślnej aktualizacji (true), czy nie (false). Obiekt Updater ustawia tę wartość podczas wywołania metody initialize(). Program powinien sprawdzać, czy właściwość isFirstRun jest ustawiona na true, jeśli istnieje potrzeba migracji danych z jednej wersji do drugiej.

Powiązane elementy interfejsu API

Funkcja, której obiekt Updater powinien używać do porównywania wersji. Domyślnie architektura aktualizacji porównuje wersje w celu wykrycia, czy wersja z witryny zdalnej jest nowsza od zainstalowanej wersji aplikacji. Jednak niekiedy domyślny sposób porównywania nie jest zgodny z systemem oznaczania wersji przyjętym przez programistę. Ta właściwość umożliwia określenie nowej funkcji realizującej porównanie.

Domyślna funkcja porównująca przyjmuje numery wersji w postaci x.y.z, gdzie x, y, i z mogą zawierać litery i cyfry. Domyślna funkcja porównująca rozpoznaje pewne sytuacje szczególne. Jeśli funkcja testująca znajdzie w ciągu wersji ciąg znaków "alpha", "beta", lub "rc", to obowiązuje zasada alpha < beta < rc.

appUpdate.isNewerVersionFunction = customFn; 

function customFn (currentVersion:String, updateVersion:String):Boolean 
{
    return updateVersion > currentVersion;
}

Poprzednie położenie katalogu magazynu aplikacji, jeśli zmieniło się po aktualizacji. Położenie katalogu magazynu aplikacji zmienia się po uaktualnieniu, któremu towarzyszy migracja certyfikatu. Jeśli nie ma miejsca migracja certyfikatu, katalog magazynu aplikacji nie ulega zmianie podczas aktualizacji aplikacji. Wówczas ta właściwość przyjmuje wartość null. Wartość tej właściwości jest przypisywana podczas wywołania metody initialize().

Programista może podpisać nową wersję aplikacji AIR nowym certyfikatem, korzystając z opcji -migrate podczas tworzenia pakietu z plikiem AIR za pomocą programu ADT. Jeśli do podpisania nowej wersji aplikacji AIR użyty został nowy certyfikat, katalog magazynu lokalnego aplikacji zmieni się, gdy użytkownik zainstaluje nową wersję. Ta właściwość umożliwia przeniesienie danych ze starego katalogu magazynu aplikacji do nowego katalogu magazynu aplikacji (File.applicationStorageDirectory). Więcej informacji zawiera sekcja „Podpisywanie pliku AIR w celu zmiany certyfikatu aplikacji” w rozdziale „Tworzenie aplikacji AIR za pomocą narzędzi wiersza poleceń” podręcznika programowania w środowisku Adobe AIR.

Poprzednia wersja aplikacji. Wartość tej właściwości jest przypisywana podczas wywołania metody initialize(). Zwraca numer poprzedniej wersji aplikacji przed uaktualnieniem (wartość przypisana tylko wtedy, gdy właściwość isfirstRun jest równa true); w przeciwnym razie przyjmuje wartość null.

Treść pliku deskryptora aktualizacji pobranego spod adresu URL aktualizacji. Ta właściwość ma wartość różną od null tylko wtedy, gdy obiekt Updater wywołuje zdarzenie updateStatus.

Położenie pliku deskryptora aktualizacji. Dozwolone jest każde położenie, jakiego można użyć w ścieżce URLRequest. Jest to jedyne ustawienie obowiązkowe wymagane przez obiekt Updater. Adres URL aktualizacji można określić albo za pośrednictwem tej właściwości, albo w pliku konfiguracyjnym. Gdy wartość jest określona na oba sposoby, obiekt Updater przyjmuje wartość przypisaną tej właściwości.

Określa, czy istniała aktualizacja odłożona w czasie, nawet jeśli jej instalacja nie powiodła się (true); false w przeciwnym wypadku. Obiekt Updater przypisuje wartość tej właściwości podczas wywołania metody initialize(). Właściwości wasPendingUpdate i isFirstRun umożliwiają sprawdzenie, czy instalacja aktualizacji nie powiodła się (wówczas wasPendingUpdate przyjmuje wartość true, a isFirstRun przyjmuje wartość false).

Powiązane elementy interfejsu API

Funkcja konstruktora.

Anuluje proces aktualizacji. Wywołanie tej metody anuluje wszystkie oczekujące operacje pobierania, usuwa wszystkie nie w pełni pobrane pliki i ponownie uruchamia zegar odliczający interwał między sprawdzeniami dostępności aktualizacji.

Proces aktualizacji można anulować w dowolnym momencie, o ile tylko maszyna stanu nie jest w stanie "UNINITIALIZED" ani "INITIALIZING". Metoda nie wykonuje żadnych czynności, jeśli zostanie wywołana w stanie "UNINITIALIZED" lub "INITIALIZING".

Asynchronicznie pobiera i interpretuje plik deskryptora aktualizacji. Wywołanie tej metody powoduje przejście obiektu Updater w stan "CHECKING". Tę metodę należy wywoływać tylko po anulowaniu zdarzenia checkForUpdate.

Ta metoda jest wykonywana tylko wtedy, gdy obiekt Updater znajduje się w stanie "BEFORE_CHECKING".

Rozpoczyna proces aktualizacji. Wywołanie tej metody nie powoduje zatrzymania licznika czasu opóźnienia między sprawdzaniem dostępności aktualizacji; metoda wykrywa jednak uruchomiony proces aktualizacji i pomija bieżącą iterację.

Ta metoda jest wykonywana tylko wtedy, gdy bieżący stan to "READY".

Wywołanie tej metody może spowodować, że obiekt Updater wywoła następujące zdarzenie:

Asynchronicznie pobiera plik aktualizacji. Wywołanie tej metody powoduje przejście maszyny stanu w stan "DOWNLOADING". Tę metodę trzeba wywoływać tylko jeśli zdarzenie StatusUpdateEvent.UPDATE_STATUS zostało anulowane, gdy właściwość available zdarzenia miała wartość true.

Ta metoda jest wykonywana tylko wtedy, gdy bieżący stan to "AVAILABLE".

Inicjuje obiekt Updater. Po wywołaniu metoda wykonuje następujące operacje:

1. Inicjuje architekturę aktualizacji i cicho (oraz synchroniczne) instaluje wszelkie oczekujące aktualizacje. Metodę tę należy wywołać w fazie uruchamiania aplikacji, ponieważ może spowodować ponowne jej uruchomienie.

2. Sprawdza, czy istnieje oczekująca (odłożona w czasie) aktualizacja, a jeśli tak, instaluje ją.

3. Jeśli wcześniejsza aktualizacja nie powiodła się, usuwa z pamięci informacje o pliku aktualizacji i o wersji.

4. Jeśli upłynął czas opóźnienia między automatycznym sprawdzaniem dostępności aktualizacji, rozpoczyna aktualizację; w przeciwnym razie uruchamia licznik czasu opóźnienia. Jednak podczas testowania aplikacji za pomocą programu AIR Debug Launcher (ADL) próba zaktualizowania aplikacji spowoduje wygenerowanie wyjątku IllegalOperationError.

Rozpoczyna proces aktualizacji przy użyciu lokalnego pliku AIR.

Wywołanie tej metody nie odnosi skutku, jeśli trwa już proces aktualizacji (w stanie innym niż "DOWNLOADED").

Ta funkcja jest przydatna w aplikacjach, dla których w pliku deskryptora element customUpdateUI jest ustawiony na true.

Podczas testowania aplikacji za pomocą aplikacji ADL (AIR Debug Launcher) wywoływanie tej metody powoduje wygenerowanie wyjątku IllegalOperationError.

Parametry

Instaluje plik aktualizacji. Wywołanie metody powoduje przejście maszyny stanu w stan "INSTALLING" i jest konieczne tylko jeśli zdarzenie downLoadComplete zostało anulowane.

Metodę należy wywoływać, gdy obiekt Updater jest w stanie "DOWNLOADED". Wywołanie jej w jakimkolwiek innym stanie nie odniesie żadnego skutku.

Podczas testowania aplikacji za pomocą aplikacji ADL (AIR Debug Launcher), wywoływanie tej metody powoduje wygenerowanie wyjątku IllegalOperationError.

Wywoływane tuż przed zainstalowaniem aktualizacji, po wywołaniu metody installUpdate(). Niekiedy celowe jest uniemożliwienie instalacji na tym etapie, ponieważ użytkownik mógłby utracić wszystkie wyniki pracy po zakończeniu pracy aplikacji wymuszonym w celu zainstalowania aktualizacji.

Wywołanie metody preventDefault() obiektu zdarzenia powoduje odłożenie instalacji do momentu następnego uruchomienia aplikacji. Po wywołaniu metody preventDefault() nie jest możliwe uruchomienie jakiegokolwiek następnego procesu aktualizacji w tej sesji aplikacji (poprzez wywołanie metody installUpdate() lub po automatycznym okresowym sprawdzeniu).

Domyślne zachowanie biblioteki ApplicationUpdater polega na pobraniu pliku deskryptora aktualizacji. Aby anulować to zachowanie, można wywołać metodę preventDefault().

To zdarzenie ma następujące właściwości:

Wywoływane przed rozpoczęciem procesu aktualizacji, tuż zanim obiekt Updater podejmie próbę pobrania pliku deskryptora aktualizacji. Obiekt Updater może wywołać to zdarzenie w wyniku bezpośredniego wywołania metody checkNow() lub po upływie czasu odmierzanego przez licznik opóźnienia między sprawdzaniem dostępności aktualizacji.

To zdarzenie ma następujące właściwości:

Wywoływane po ukończeniu pobierania pliku aktualizacji.

Zwykle to zdarzenie jest wykorzystywane do wyświetlenia pytania, czy użytkownik chce rozpocząć instalowanie aktualizacji.

Domyślne zachowanie klasy ApplicationUpdater polega na automatycznym wywołaniu metody installUpdate().

To zdarzenie ma następujące właściwości:

Wywoływane, jeśli podczas nawiązywania połączenia lub pobierania pliku aktualizacji wystąpi błąd. To zdarzenie jest także wywoływane w wypadku odebrania niepoprawnego statusu HTTP (np. „404 - nie znaleziono pliku”).

Z chwilą wywołania tego zdarzenia automatycznie uruchamiany jest licznik czasu (jeśli opóźnienie jest większe od 0).

Właściwość errorID obiektu DownloadErrorEvent jest liczbą całkowitą definiującą informacje o błędzie (zob. poniższą tabelę). Dodatkowa właściwość subErrorID może zawierać dalsze informacje o błędzie.

Wywoływane po wywołaniu metody downloadUpdate() i nawiązaniu połączenia z serwerem. W przypadku użycia biblioteki ApplicationUpdater często stosowanym rozwiązaniem jest wyświetlanie paska postępu pobierania w procedurze obsługi tego zdarzenia.

To zdarzenie ma następujące właściwości:

Wywoływane, gdy wystąpi błąd podczas inicjowania lub podczas procesu aktualizacji (w razie zajścia nieoczekiwanego zdarzenia).

To zdarzenie ma następujące właściwości:

Wywoływane, gdy wystąpi błąd podczas weryfikacji pliku przekazanego jako parametr airFile w wywołaniu metody installFromAIRFile().

Wywoływane po tym, jak obiekt Updater pomyślnie zweryfikuje plik w wywołaniu metody installFromAIRFile().

To zdarzenie ma następujące właściwości:

Wywoływane po zakończeniu inicjowania.

To zdarzenie ma następujące właściwości:

Wywoływane w chwili pobrania pliku aktualizacji.

To zdarzenie ma następujące właściwości:

Wywoływane, gdy wystąpi błąd przy próbie pobrania lub przeanalizowania pliku deskryptora aktualizacji.

Gdy obiekt Updater wywoła to zdarzenie, automatycznie uruchamiany jest licznik czasu (jeśli opóźnienie jest ustawione na wartość większą niż 0). Wskazane jest, aby aplikacja ukrywała wszelkie okna dialogowe błędów, gdy obiekt Updater wywoła nowe zdarzenie checkForUpdate.

Wywoływane po tym, jak obiekt Updater pomyślnie pobierze i zinterpretuje plik deskryptora aktualizacji.

Zachowanie domyślne polega na rozpoczęciu pobierania aktualizacji, jeśli właściwość available obiektu StatusUpdateEvent jest ustawiona na true. Zachowanie domyślne można zablokować tylko w przypadku użycia klasy ApplicationUpdater, a nie klasy ApplicationUpdatorUI.

To zdarzenie ma następujące właściwości: