• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1/*
2 * Copyright (c) 2022 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16
17/**
18 *
19 *   SubscribedAbstractProperty is base class of ObservedPropertyAbstract
20 *   and includes these 3 functions that are part of the SDK.
21 *
22 *   SubscribedAbstractProperty<T> is the return type of
23 *   - AppStorage static functions Link(), Prop(), SetAndLink(), and SetAndProp()
24 *   - LocalStorage methods link(), prop(), setAndLink(), and setAndProp()
25 *
26 *   'T' can be boolean, string, number or custom class.
27 *
28 * Main functions
29 *   @see get() reads the linked AppStorage/LocalStorage property value,
30 *   @see set(newValue) write a new value to the synched AppStorage/LocalStorage property value
31 *   @see aboutToBeDeleted() ends the sync relationship with the AppStorage/LocalStorage property
32 *        The app must call this function before the SubscribedAbstractProperty<T> object
33 *        goes out of scope.
34 *
35 * @since 7
36*/
37
38abstract class SubscribedAbstractProperty<T> {
39     /**
40      * reads value of the sync'ed AppStorage/LocalStorage property.
41      *
42      * @since 7
43      *
44      */
45     public abstract get(): T;
46
47     /**
48      * Set new value, must be of type T, and must not be 'undefined' or 'null'.
49      * Updates the value of value of the sync'ed AppStorage/LocalStorage property.
50      *
51      * @param newValue
52      *
53      * @since 7
54      */
55     public abstract set(newValue: T): void;
56
57     /**
58      * An app needs to call this function before the instance of SubscribedAbstractProperty
59      * goes out of scrope / is subject to garbage collection. Its purpose is to unregister the
60      * variable from the tw0-way/one-way sync relationship that AppStorage/LocalStorage.link()/prop()
61      * and related functions create.
62      *
63      * @since 7
64      */
65     public abstract aboutToBeDeleted(): void;
66
67
68     /**
69      * @return the property name if set or undefined
70      *
71      * @since 7
72      */
73     public abstract info(): string;
74
75     /**
76      * @return the number of current subscribers
77      * This info is useful because only a property with no subscribers is allowed
78      * to be deleted / let out of scope
79      *
80      * @since 7
81      */
82     public abstract numberOfSubscrbers(): number;
83
84     /**
85      * Notify the property value would have changed.
86      * The framework calls this function automatically upon @see set().
87      * An application should NOT use this function!
88      *
89      * @since 7, depreciated, do NOT use!
90      */
91     protected abstract notifyHasChanged(newValue: T);
92
93     /**
94      * Notify the property value would have been read.
95      * The framework calls this function automatically upon @see get()
96      * if it needs this information (usually during initial render of a @Component)
97      * An application should NOT use this function!
98      *
99      * @since 7, depreciated, do NOT use!
100      */
101     protected abstract notifyPropertyRead();
102
103
104     /**
105      * Create a new SubscribedAbstractProperty<T> and establish a two-way sync with this property.
106      * We found that managing a 'chain' of SubscribedAbstractProperty<T> is hard to manage and in consequence
107      * easily gets broken by one object being GC'ed. Therefore we have depreciated this method. Do not use it!
108      *
109      * @since 7, depreciated.
110      *
111      */
112     public abstract createTwoWaySync(subscribeMe?: IPropertySubscriber, info?: string): SubscribedAbstractProperty<T>;
113
114     /**
115      * Create a new SubscribedAbstractProperty<T> and establish a one-way sync with this property.
116      * We found that managing a 'chain' of SubscribedAbstractProperty<T> is hard to manage and in consequence
117      * easily gets broken by one object being GC'ed. Therefore we have depreciated this method. Do not use it!
118      *
119      * @since 7, depreciated.
120      *
121      */
122     public abstract createOneWaySync(subscribeMe?: IPropertySubscriber, info?: string): SubscribedAbstractProperty<T>;
123}