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

Jump to bottom

MQTT, SECSI doc updates #6317

Merged
merged 3 commits into from
Dec 17, 2018
Merged

MQTT, SECSI doc updates #6317

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
933e6be
MQTT, SECSI doc updates
bobjacobsen Dec 11, 2018
d1f3d6d
scanhelp
bobjacobsen Dec 17, 2018
0ec6e1f
add MQTT to index and TOC
bobjacobsen Dec 17, 2018
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
Binary file modified help/en/JavaHelpSearch/DOCS
View file
Open in desktop
Binary file not shown.
Binary file modified help/en/JavaHelpSearch/DOCS.TAB
View file
Open in desktop
Binary file not shown.
Binary file modified help/en/JavaHelpSearch/OFFSETS
View file
Open in desktop
Binary file not shown.
Binary file modified help/en/JavaHelpSearch/POSITIONS
View file
Open in desktop
Binary file not shown.
2 changes: 1 addition & 1 deletion help/en/JavaHelpSearch/SCHEMA
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
JavaSearch 1.0
TMAP bs=2048 rt=77 fl=-1 id1=16667 id2=1
TMAP bs=2048 rt=71 fl=-1 id1=16693 id2=1
Binary file modified help/en/JavaHelpSearch/TMAP
View file
Open in desktop
Binary file not shown.
2 changes: 2 additions & 0 deletions help/en/JmriHelp_enIndex.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -312,6 +312,8 @@

<indexitem text="MRC " target="html.hardware.mrc.index"/>

<indexitem text="MQTT " target="html.hardware.mqtt.index"/>

<indexitem text="Multi-Decoder Control " target="package.jmri.jmrit.dualdecoder.DualDecoderSelectFrame"/>

<indexitem text="Naming JMRI Objects " target="html.doc.Technical.Names"/>
Expand Down
2 changes: 2 additions & 0 deletions help/en/JmriHelp_enTOC.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,8 @@

<tocitem text="MRC " target="html.hardware.mrc.index"/>

<tocitem text="MQTT " target="html.hardware.mqtt.index"/>

<tocitem text="NCE " target="html.hardware.nce.NCE"/>

<tocitem text="OakTree Systems " target="html.hardware.oaktree.OakTree"/>
Expand Down
14 changes: 14 additions & 0 deletions help/en/Map.jhm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -540,6 +540,8 @@

<mapID target="html.hardware.XPressNet.index_connectElite" url="html/hardware/XPressNet/index.shtml#connectElite"/>

<mapID target="html.hardware.mqtt.index_connecting" url="html/hardware/mqtt/index.shtml#connecting"/>

<mapID target="manual.DecoderPro3.Programmer_Setup_Setting_Up" url="manual/DecoderPro3/Programmer_Setup.shtml#Setting_Up"/>

<mapID target="package.jmri.jmrix.rps.trackingpanel.RpsTrackingFrame" url="package/jmri/jmrix/rps/trackingpanel/RpsTrackingFrame.shtml"/>
Expand Down Expand Up @@ -918,6 +920,8 @@

<mapID target="manual.DecoderPro3.Comp_Setup_Roster_Top" url="manual/DecoderPro3/Comp_Setup_Roster.shtml#Top"/>

<mapID target="package.jmri.jmrix.can.cbus.swing.configtool.ConfigToolFrame_filterhighlight" url="package/jmri/jmrix/can/cbus/swing/configtool/ConfigToolFrame.shtml#filterhighlight"/>

<mapID target="html.hardware.loconet.StandaloneLocoNet_examples" url="html/hardware/loconet/StandaloneLocoNet.shtml#examples"/>

<mapID target="html.hardware.dccpp.Turnouts_types" url="html/hardware/dccpp/Turnouts.shtml#types"/>
Expand Down Expand Up @@ -1792,6 +1796,8 @@

<mapID target="html.apps.DecoderPro.FAQ_update" url="html/apps/DecoderPro/FAQ.shtml#update"/>

<mapID target="package.jmri.jmrix.can.cbus.swing.cbusslotmonitor.CbusSlotMonitorPane_cabdata" url="package/jmri/jmrix/can/cbus/swing/cbusslotmonitor/CbusSlotMonitorPane.shtml#cabdata"/>

<mapID target="html.hardware.loconet.StandaloneLocoNet_isolthrdetsig" url="html/hardware/loconet/StandaloneLocoNet.shtml#isolthrdetsig"/>

<mapID target="html.tools.TimeTable_technical" url="html/tools/TimeTable.shtml#technical"/>
Expand Down Expand Up @@ -2070,6 +2076,8 @@

<mapID target="manual.JMRI_OPS_UsersGuide.Ops_BuildReportPrint" url="manual/JMRI_OPS_UsersGuide/Ops_BuildReportPrint.shtml"/>

<mapID target="html.hardware.mqtt.index_limitations" url="html/hardware/mqtt/index.shtml#limitations"/>

<mapID target="manual.JMRI_OPS_UsersGuide.Ops_CarAttributes_Top" url="manual/JMRI_OPS_UsersGuide/Ops_CarAttributes.shtml#Top"/>

<mapID target="html.doc.Technical.GitFAQ" url="html/doc/Technical/GitFAQ.shtml"/>
Expand Down Expand Up @@ -2636,6 +2644,8 @@

<mapID target="package.jmri.jmrit.display.EditLayoutSlip" url="package/jmri/jmrit/display/EditLayoutSlip.shtml"/>

<mapID target="package.jmri.jmrix.can.cbus.swing.console.CbusConsoleFrame_filter" url="package/jmri/jmrix/can/cbus/swing/console/CbusConsoleFrame.shtml#filter"/>

<mapID target="html.hardware.PDA_documentation" url="html/hardware/PDA.shtml#documentation"/>

<mapID target="html.doc.Technical.CVSFAQ_ds_store" url="html/doc/Technical/CVSFAQ.shtml#ds_store"/>
Expand Down Expand Up @@ -2884,6 +2894,8 @@

<mapID target="html.tools.throttle.ThrottleChapter2_ControlPanel" url="html/tools/throttle/ThrottleChapter2.shtml#ControlPanel"/>

<mapID target="html.hardware.mqtt.index" url="html/hardware/mqtt/index.shtml"/>

<mapID target="manual.DecoderPro.Installing_JMRI_Top" url="manual/DecoderPro/Installing_JMRI.shtml#Top"/>

<mapID target="package.jmri.jmrix.secsi.serialmon.SerialMonFrame" url="package/jmri/jmrix/secsi/serialmon/SerialMonFrame.shtml"/>
Expand Down Expand Up @@ -3638,6 +3650,8 @@

<mapID target="manual.JMRI_OPS_UsersGuide.index_Main" url="manual/JMRI_OPS_UsersGuide/index.shtml#Main"/>

<mapID target="package.jmri.jmrix.can.cbus.swing.console.CbusConsoleFrame_eventcapture" url="package/jmri/jmrix/can/cbus/swing/console/CbusConsoleFrame.shtml#eventcapture"/>

<mapID target="html.hardware.grapevine.index_connecting" url="html/hardware/grapevine/index.shtml#connecting"/>

<mapID target="html.hardware.can.cbus.Names_summary" url="html/hardware/can/cbus/Names.shtml#summary"/>
Expand Down
247 changes: 247 additions & 0 deletions help/en/html/doc/Technical/Enums.shtml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,247 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>

<title>
JMRI: Using Enums
</title>
<meta name="author" content="YOUR NAME HERE">
<meta name="keywords" content="SOME KEYWORDS">

<!--#include virtual="/Style.shtml" -->
</head>
<!--#include virtual="/Header.shtml" -->

<body>
<div id="mBody">
<!--#include virtual="Sidebar.shtml" --> <!-- select the local or global Sidebar file -->
<div id="mainContent">

<h1>JMRI: Using Enums</h1>

<h2>The Minimal Enum</h2>

<p>The minimal enum is really small. Here's
an example of embedding an enum in a class to
represent seven different constants:</p>

<pre style="font-family: monospace;">
class MyClass {
public enum Day {
SUNDAY, MONDAY, TUESDAY, WEDNESDAY,
THURSDAY, FRIDAY, SATURDAY
}

void checkParty(Day day) {
if (day == Day.FRIDAY) {
doParty();
}
}
}
</pre>

<ul>
<li>This shows a lightweight enum embedded in one class,
but you can also define them independently.
<li>Another class can refer to this as
<code>MyClass.Day</code> and <code>MyClass.Day.FRIDAY</code>
</ul>
<p>
Examples of use:</p>

<pre style="font-family: monospace;">
for (Day day : Day.values()) {
// do what you want
}
</pre>

<pre style="font-family: monospace;">
String whichDay = "THURSDAY";
Day day = Day.valueOf(whichDay);
checkParty(day); // disappointment!
checkParty(Day.TUESDAY); // disappointment!
</pre>

<p>
Note there are no meaningful integer values for this.</p>

<h2>Migrating Integer Constants to Enum</h2>

<p>If you have a set of constants like</p>

<pre style="font-family: monospace;">
static final int DOG = 1;
static final int CAT = 2;
static final int FISH = 3;
static final int BIRD = 12;
</pre>

<p>converting those to an enum can make them more type-safe.</p>

<pre style="font-family: monospace;">
public enum Pet {
DOG(1),
CAT(2),
FISH(3),
BIRD(12);

private final int value;
Pet(int v) { value = v; }
int asInt() { return value; }
}
</pre>

<p>To use this, just replace "int" with "Pet" where-ever one is
defined or passed as a parameter. Then compile and see
what else needs to be changed; if you're not doing arithmetic
with the constants (in which case maybe they're not enums),
there shouldn't be much else that needs to be changed.</p>

<pre style="font-family: monospace;">
void check(int val) {
switch (val) {
case DOG:
// do stuff and return
case CAT:
// do stuff and return
default:
// do stuff and return
}
}
</pre>

<p>becomes</p>

<pre style="font-family: monospace;">
void check(Pet val) {
switch (val) {
case DOG:
// do stuff and return
case CAT:
// do stuff and return
default:
// do stuff and return
}
}
</pre>

<p>(The only change was in the 1st line)</p>

<h2>Adding String Values</h2>

<p>Sometimes you want the elements to also have
user-readable names separate from the
names of the individual items. For example,
you might want to call it TUESDAY in the code,
but have it provide "Tuesday" for pretty printing.</p>

<pre style="font-family: monospace;">
public enum NamedPet {
DOG(1, "Dog"),
CAT(2, "Cat"),
FISH(3, "Fish"),
BIRD(12, "Bird");

private final int value;
private final String name;
Pet(int v, string s) {
value = v;
name = s;
}
int asInt() { return value; }
String toString() { return name; }
}
</pre>

<p>
Note that you might want to internationalize these in the constructor.
See
<a href="https://github.com/JMRI/JMRI/blob/master/java/src/jmri/LocoAddress.java">java/src/jmri/LocoAddress.java</a> for an example of this.
</p>

<p>
In general, you should <u>not</u> build a lot of
code to convert between ints and Enums or between Strings and enums.
That's a code smell that indicates something wrong with how you're
using the enums. If users have to select a specific one, for example, provide a combobox
of values, don't have them type a String that you then have to error-check and
convert. </p>

<p>
The one exception to this is the ConvertXML persistance system,
which wants to convert your enum values to and from String values
to store and load in XML files, and may also need to convert from the numeric values for
historical reasons. See below.</p>

<h2>ConvertXML</h2>

<p>
Enums can provide interfaces. We use the
<code>StringConvertibleEnum</code> and
<code>IntConvertibleEnum</code>
interfaces as flags.


<h4>Migration</h4>

Start writing a new schema that only allows the specific elements,
but make sure your code can take the old numeric values.
Since the file contains the schema it obeys, this is OK.

But it might require a lot of migrations if you do this
between test releases....



<h4>Schema limiting to a set of specific enum values</h4>

<pre style="font-family: monospace;">
&lt;xs:attribute name="connection" default="unspecified" &gt;
&lt;xs:simpleType&gt;
&lt;xs:restriction base="xs:token" &gt;
&lt;xs:enumeration value="unspecified"/&gt;
&lt;xs:enumeration value="plug"/&gt;
&lt;xs:enumeration value="wire"/&gt;
&lt;xs:enumeration value="solder"/&gt;
&lt;xs:enumeration value="LED"/&gt;
&lt;xs:enumeration value="bulb"/&gt;
&lt;xs:enumeration value="other"/&gt;
&lt;/xs:restriction&gt;
&lt;/xs:simpleType&gt;
&lt;/xs:attribute&gt;
</pre>

<h4>Schema also permitting older numeric values</h4>

<pre style="font-family: monospace;">
&lt;xs:attribute name="size"&gt;
&lt;xs:simpleType&gt;
&lt;xs:union&gt;
&lt;xs:simpleType&gt;
&lt;xs:restriction base="xs:positive-integer"&gt;
&lt;xs:maxInclusive="10"/&gt;
&lt;/xs:restriction&gt;
&lt;/xs:simpleType&gt;
&lt;xs:simpleType&gt;
&lt;xs:restriction base="xs:NMTOKEN"&gt;
&lt;xs:enumeration value="small"/&gt;
&lt;xs:enumeration value="medium"/&gt;
&lt;xs:enumeration value="large"/&gt;
&lt;/xs:restriction&gt;
&lt;/xs:simpleType&gt;
&lt;/xs:union&gt;
&lt;/xs:simpleType&gt;
&lt;/xs:attribute&gt;
</pre>

This can also be used for elements (which is the generally prefered approach)




<!--#include virtual="/Footer.shtml" -->

</div><!-- closes #mainContent-->
</div> <!-- closes #mBody, was opened by Sidebar -->
</body>
</html>
19 changes: 19 additions & 0 deletions help/en/html/hardware/index.shtml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -375,6 +375,18 @@
"modbus/index.shtml">Modbus networks</a></p>
</dd>


<dt class="im"><img src=
"http://mqtt.org/new/wp-content/uploads/2012/02/mqtt-inside.png"
alt="MQTT logo" height="60" width="60"></dt>

<dt><a href="mqtt/index.shtml">MQTT</a></dt>

<dd>
<p class="dl">Configure: <a href=
"mqtt/index.shtml">MQTT networks</a></p>
</dd>

<dt class="im"><a href="http://www.modelrectifier.com">
<img src="http://www.modelrectifier.com/v/vspfiles/templates/modelRecRes/images/template/desktop/client-logo.png" alt="MRC logo" height="43" width="103">
</a></dt>
Expand Down Expand Up @@ -562,6 +574,13 @@
station.</p>
</dd>

<dt><a href="secsi/index.shtml">TracTronics SECSI</a></dt>

<dd>
<p class="dl">Configure: <a href=
"secsi/index.shtml">TracTronics SECSI connections</a></p>
</dd>

<dt class="im"><a href=
"http://www.uhlenbrock.de/"><img src="images/ico-Ur.gif"
width="44" height="34" alt="Uhlenbrock"></a></dt>
Expand Down
Loading