Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Additional improvements to persistence article #535

Merged
merged 8 commits into from
Nov 3, 2017
Merged

Additional improvements to persistence article #535

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
02f73a8
Additional improvements to persistence article
bgilmer77 Oct 20, 2017
523b98f
Improve readability of Strategies and Items sections
bgilmer77 Oct 23, 2017
66525f1
Address numerous comments from @ThomDietrich
bgilmer77 Oct 23, 2017
4d181fc
Finishes "nit" pass through Persistence article
bgilmer77 Oct 31, 2017
a6768d6
Expand explanation of how one may specify persistence for an Item
bgilmer77 Oct 31, 2017
52ed5d4
Correct formating of Persistence Extensions
bgilmer77 Nov 3, 2017
7f5c0df
Format Persistence Extensions as a table
bgilmer77 Nov 3, 2017
c1cd6c6
Fix markdown table style
Nov 3, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 45 additions & 18 deletions configuration/persistence.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,11 @@ openHAB can store data over time; this is known as persistence.
The data may be retrieved at a later time, for example to restore your system after startup, or to prepare graphs for display on a UI.

openHAB persists Item states in a database, and most popular databases are supported.
You may have more that one persistence add-on loaded, and each of these may be configured independently.
You may have more than one persistence add-on loaded, and each of these may be configured independently.

A complete list of supported persistence add-ons may be found in the [persistence]({{base}}/addons/persistence.html) section of the on-line openHAB documentation.

## Persistence Add-on Configuration
## Add-on Configuration
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Once about the "Configuration" headline issue. I think it would best be solved if you simply removed this one.
wdyt?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes - that makes sense.


Each persistence add-on you install will need to be configured.
Please refer to the specific [on-line documentation]({{base}}/addons/persistence.html) for your selected persistence add-on for configuration instructions.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In most other articles we are linking the subject directly. I.e.

Please refer to the documentation of available persistence service add-ons for configuration instructions.

(besides I for one would write online instead of on-line...?)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed to, "Please refer to the available persistence service add-on documentation for your selected persistence add-on for configuration instructions."

Expand All @@ -31,7 +31,7 @@ Scroll down to "Persistence", and select your Default Service from the drop-down
Note that you must first install a persistence add-on before you make this selection.
Be sure to save your choice once you have selected your default service.

## Configuration
## Item Persistence Configuration

Persistence Strategies are configured in a file named `<persistenceservice>.persist`, stored in `$OPENHAB_CONF/persistence` ("persistenceservice" is replaced by the name of your add-on (e.g. `rrd4j.persist`)).

Expand All @@ -46,10 +46,14 @@ This section allows you to define strategies and to declare a set of default str
```java
Strategies {
<strategyName1> : "cronexpression1>"

default = everyChange
...
}
```

If no strategy is specified in an `itemlist` as described in the Items section below, the `default` strategy will be applied. The `default` parameter is optional and may be omitted.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. Please break down to one line per sentence.
  2. This may be a bit confusing for beginners.
    On one side the default parameter is used when no other is given but in the next sentence this is explained as optional.
    Maybe it would be good to make clear that default has to be set when one doesn't want to use explicit strategies only.

Its maybe a really small thing, but i stocked while reading through it and wanted to mention it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree completely. How about this...

The default parameter assigns a strategy to be used if one is not specified in the Items section below.
The default parameter may be omitted from the Strategies section, but if and only if a strategy is provided in each line of the Items section.

Replace the text in the Items section with the following:
Note: if the strategy portion of the itemlist is omitted, the default strategy specified in the Strategies section will be applied.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good. 👍


The following strategies are defined internally:

- everyChange: persist the Item state whenever its state has changed
Expand All @@ -63,13 +67,16 @@ The syntax is as follows:

```java
Items {
<itemlist1 [-> "<alias1>"] : [strategy = <strategy1>, <strategy2>, ...]
<itemlist1> [-> "<alias1>"] : [strategy = <strategy1>, <strategy2>, ...]
<itemlist2> [-> "<alias2>"] : [strategy = <strategyX>, <strategyY>, ...]
...

}
```

Note that you may omit the `strategy` portion of the `itemlist` so long as you have provided a `default` strategy in the `Strategies` section.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so long as => as long as

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah - 'so long as' and 'as long as' are superfine distinctions in English. 'as long as' is much more common, so this is what I should use in a document being read by people from all over the world. In any case, I am proposing to replace all of this anyway, but thank you for pointing this out.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ahh - from dictionary.cambridge.org (what do they know about English??!!)
As long as: refer to the intended duration of a plan or idea
As long as and so long as: means 'provided that", 'providing that" or 'on condition that'. So long as is a little informal.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be honest i didn't think of any rules. It sounded strange to me while reading. 😄
That was my intention to comment it here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree. Well, I will rewrite the section and drop this strange wording anyway.

In this case, the default strategy will be applied.

where `<itemlist>` is a comma-separated list consisting of one or more of the following options:

- `*` - this line should apply to all items in the system
Expand Down Expand Up @@ -139,20 +146,40 @@ You can easily imagine that you can implement very powerful rules using this fea

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the unchanged part above, please capitalize headlines

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay - will ensure all headlines are capitalized in the entire article.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This comment has been addressed

Here is the full list of available persistence extensions:

```java
<item>.persist - Persists the current state
<item>.lastUpdate - Query for the last update timestamp of a given Item.
<item>.historicState(AbstractInstant) - Retrieves the historic Item at a certain point in time
<item>.changedSince(AbstractInstant) - Checks if the state of the Item has (ever) changed since a certain point in time
<item>.updatedSince(AbstractInstant) - Checks if the state of the Item has been updated since a certain point in time
<item>.maximumSince(AbstractInstant) - Gets the Item with the maximum value (state) since a certain point in time
<item>.minimumSince(AbstractInstant) - Gets the Item with the minimum value (state) since a certain point in time
<item>.averageSince(AbstractInstant) - Gets the average value of the state of a given Item since a certain point in time.
<item>.deltaSince(AbstractInstant) - Gets the difference value of the state of a given Item since a certain point in time.
<item>.previousState() - Retrieves the previous Item (returns HistoricItem).
<item>.previousState(true) - Retrieves the previous Item, skips items with equal state values and searches the first Item with state not equal the current state (returns HistoricItem).
<item>.sumSince(AbstractInstant) - Retrieves the sum of the previous states since a certain point in time. (OpenHab 1.8)
```
- <item>.persist - Persists the current state


- <item>.lastUpdate - Query for the last update timestamp of a given Item.


- <item>.historicState(AbstractInstant) - Retrieves the historic Item at a certain point in time


- <item>.changedSince(AbstractInstant) - Checks if the state of the Item has (ever) changed since a certain point in time


- <item>.updatedSince(AbstractInstant) - Checks if the state of the Item has been updated since a certain point in time


- <item>.maximumSince(AbstractInstant) - Gets the Item with the maximum value (state) since a certain point in time


- <item>.minimumSince(AbstractInstant) - Gets the Item with the minimum value (state) since a certain point in time


- <item>.averageSince(AbstractInstant) - Gets the average value of the state of a given Item since a certain point in time


- <item>.deltaSince(AbstractInstant) - Gets the difference value of the state of a given Item since a certain point in time


- <item>.previousState() - Retrieves the previous Item (returns HistoricItem)


- <item>.previousState(true) - Retrieves the previous Item, skips items with equal state values and searches the first Item with state not equal the current state (returns HistoricItem)


- <item>.sumSince(AbstractInstant) - Retrieves the sum of the previous states since a certain point in time. (OpenHab 1.8)

These extensions use the default persistence service that is configured as the default persistence service. (Refer to Default Persistence Service above to configure this.)

Expand Down