Projects tigase _server server-core Issues #756
Kernel/Bootstrap documentation (#756)
wojciech.kapcia@tigase.net opened 8 years ago
Due Date
2017-04-06

Currently we are missing documentation similar to Component Implementation - Lesson 8 - Startup Time (and Development Guide altogether, currently getDefaults()@/@setProperties() causes WARNINGS about deprecated methods)

Andrzej Wójcik (Tigase) commented 8 years ago

I've updated section about component startup, but I think we need separate sections about beans and kernel.

Andrzej Wójcik (Tigase) commented 8 years ago

I've updated whole section related to component implementation as it was using deprecated solutions. I replaced it with currently recommended design patterns and described it (now it includes Tigase Kernel, data sources usage and a lot of a new stuff).

wojciech.kapcia@tigase.net commented 8 years ago

As usual, comments:

  • Lifecycle of a component

void beanConfigurationChanged(Collection changedFields) (…) It is useful if same component internal depends on configuration stored in more than one field, as it allows you to reconfigure this internal once.

Could you rephrase this sentence? What is same component internal?

There is no way to know when all the beans were finally initialised during startup?

In Multi-threading there is following passage:

When this happens Tigase calls void initializationCompleted() method for each server component. You can overwrite this method to execute some actions at the time when you are sure the your component is initialized and configured but has not been started yet.

so shouldn't this be included in the list in Lifecycle of component?

  • Configuration API -- I think it's not needed anymore?

  • Basics

  • why String[] getFeatures() needs to be overridden with @return new String[0];@? Shouldn't it by default return empty array?

  • Now we have to remove the etc/tigase.xml file and restart the server. there is no such file;

  • service-disco-test-comp-admin-300 -- image is not showing up (I guess it's a result of Daniel's merging all docs and then separating them again?);

  • should we still see calls to .setProperties() (without causing warning) in the logs?

  • side-note not related to the dsl/kernel - if our sample cod has log.finest(…); then most likely, with default setting nothing will be printed in the logs? (AFAIR there were questions about it in the forums a while back?)

  • Service discovery:

    • _One of the limitations of methods above is that you can not update or change component information at run-time with these methods. They are called only once during setProperties(...) method call _ -- @setProperties@?!
Andrzej Wójcik (Tigase) commented 8 years ago

Wojciech Kapcia wrote:

As usual, comments:

  • Lifecycle of a component

void beanConfigurationChanged(Collection changedFields) (…) It is useful if same component internal depends on configuration stored in more than one field, as it allows you to reconfigure this internal once.

Could you rephrase this sentence? What is same component internal?

Done, but I'm not sure if is is better.

There is no way to know when all the beans were finally initialised during startup?

No. I do not agree that there is anything that requires you to know that. You should be able to work in cases when something is not initialized, and as it is possible to change configuration, enabled/disable components at runtime which makes it impossible to tell if server is initialized at any particular point in time.

In Multi-threading there is following passage:

When this happens Tigase calls void initializationCompleted() method for each server component. You can overwrite this method to execute some actions at the time when you are sure the your component is initialized and configured but has not been started yet.

so shouldn't this be included in the list in Lifecycle of component?

I removed that, as in Lifecycle there is already mentioned initialize() method which can be used and is fired at the same time.

Removed.

** why String[] getFeatures() needs to be overridden with @return new String[0];@? Shouldn't it by default return empty array?

No, I disagree. There is not default implementation and shouldn't be a default one. Person implementing a module should be required to fill list of features provided by module.

** Now we have to remove the etc/tigase.xml file and restart the server. there is no such file;

I left it as it was. I updated documentation related to Tigase Kernel.

** service-disco-test-comp-admin-300 -- image is not showing up (I guess it's a result of Daniel's merging all docs and then separating them again?);

I have no idea. I left it as it was there. I just updated descriptions related to component implementation and Tigase Kernel.

** should we still see calls to .setProperties() (without causing warning) in the logs?

Yes, there are a few places in which we call setProperties() and getDefaults() for backward compatibility. If I'm correct calls of methods marked as @Deprecated are not logged as warnings.

** side-note not related to the dsl/kernel - if our sample cod has log.finest(…); then most likely, with default setting nothing will be printed in the logs? (AFAIR there were questions about it in the forums a while back?)

I was updating old code to our current implementation and there was log.finest(..) as it should be. Turning on debugging of a package is a separate issue. Maybe it should be added to documentation?

  • Service discovery:

** _One of the limitations of methods above is that you can not update or change component information at run-time with these methods. They are called only once during setProperties(...) method call _ -- @setProperties@?!

I've fixed that. For some reason I haven't seen this before.

wojciech.kapcia@tigase.net commented 8 years ago

Andrzej Wójcik wrote:

Could you rephrase this sentence? What is same component internal?

Done, but I'm not sure if is is better.

It is, thank you.

** why String[] getFeatures() needs to be overridden with @return new String[0];@? Shouldn't it by default return empty array?

No, I disagree. There is not default implementation and shouldn't be a default one. Person implementing a module should be required to fill list of features provided by module.

Well, by default it could return empty array, and if someone wants to provide some features this method could simply be overwritten? Looking at implementations roughly half of them return features, and most likely majority of the modules won't have to provide them so this default IMHO is odd.

** Now we have to remove the etc/tigase.xml file and restart the server. there is no such file;

I left it as it was. I updated documentation related to Tigase Kernel.

Yes, but while doing so removing obviously non-existent things makes sense? Especially that DLS is third configuration mechanism from "tigase.xml"…

** should we still see calls to .setProperties() (without causing warning) in the logs?

Yes, there are a few places in which we call setProperties() and getDefaults() for backward compatibility. If I'm correct calls of methods marked as @Deprecated are not logged as warnings.

They are:

2017-03-21 15:56:57.582 [main]             DSLBeanConfiguratorWithBackwardCompatibility.configure()  WARNING: Class tigase.server.bosh.BoshConnectionManager is using deprecated configuration using methods getDefaults() and setProperties()
Loading component: bosh :: componentInfo{Title=Tigase XMPP Server, Version=7.2.0-SNAPSHOT-b4732/7bf3ab5d (2017-03-21/00:10:58), Class=tigase.server.bosh.BoshConnectionManager}
2017-03-21 15:56:57.876 [main]             DSLBeanConfiguratorWithBackwardCompatibility.configure()  WARNING: Class tigase.stats.StatisticsCollector is using deprecated configuration using methods getDefaults() and setProperties()

At the very least documentation could describe them as deprecated and that usage should be avoided.

** side-note not related to the dsl/kernel - if our sample cod has log.finest(…); then most likely, with default setting nothing will be printed in the logs? (AFAIR there were questions about it in the forums a while back?)

I was updating old code to our current implementation and there was log.finest(..) as it should be. Turning on debugging of a package is a separate issue. Maybe it should be added to documentation?

It's covered in -debug documentation.

Afterwards you can assign it to Daniel to fix:

** service-disco-test-comp-admin-300 -- image is not showing up (I guess it's a result of Daniel's merging all docs and then separating them again?);

I have no idea. I left it as it was there. I just updated descriptions related to component implementation and Tigase Kernel.

Andrzej Wójcik (Tigase) commented 8 years ago

Wojciech Kapcia wrote:

Andrzej Wójcik wrote:

Could you rephrase this sentence? What is same component internal?

Done, but I'm not sure if is is better.

It is, thank you.

** why String[] getFeatures() needs to be overridden with @return new String[0];@? Shouldn't it by default return empty array?

No, I disagree. There is not default implementation and shouldn't be a default one. Person implementing a module should be required to fill list of features provided by module.

Well, by default it could return empty array, and if someone wants to provide some features this method could simply be overwritten? Looking at implementations roughly half of them return features, and most likely majority of the modules won't have to provide them so this default IMHO is odd.

Fine, I added default implementation in Module interface which will return always the same instance of String[]

** Now we have to remove the etc/tigase.xml file and restart the server. there is no such file;

I left it as it was. I updated documentation related to Tigase Kernel.

Yes, but while doing so removing obviously non-existent things makes sense? Especially that DLS is third configuration mechanism from "tigase.xml"…

OK, I removed it. But whole documentation of Tigase XMPP Server requires clean up, not only this part.

** should we still see calls to .setProperties() (without causing warning) in the logs?

Yes, there are a few places in which we call setProperties() and getDefaults() for backward compatibility. If I'm correct calls of methods marked as @Deprecated are not logged as warnings.

They are:

[...]

At the very least documentation could describe them as deprecated and that usage should be avoided.

I've updated components to use @ConfigField and beans instead of getDefaults() and setProperties() so now it should be fine. No calls to getDefaults() and setProperties() any more.

To do that I needed to change configuration of statistics archivers/loggers, so I updated documentation as well.

** side-note not related to the dsl/kernel - if our sample cod has log.finest(…); then most likely, with default setting nothing will be printed in the logs? (AFAIR there were questions about it in the forums a while back?)

I was updating old code to our current implementation and there was log.finest(..) as it should be. Turning on debugging of a package is a separate issue. Maybe it should be added to documentation?

It's covered in -debug documentation.

Afterwards you can assign it to Daniel to fix:

** service-disco-test-comp-admin-300 -- image is not showing up (I guess it's a result of Daniel's merging all docs and then separating them again?);

I have no idea. I left it as it was there. I just updated descriptions related to component implementation and Tigase Kernel.

I'm assigning this to %wojtek to review changes related to @StatisticsCollector@, it's archivers, etc.

Afterwards, if it will finally be ok, assign task to Daniel to fix issue mentioned above.

wojciech.kapcia@tigase.net commented 8 years ago

Andrzej Wójcik wrote:

Wojciech Kapcia wrote:

Andrzej Wójcik wrote:

** Now we have to remove the etc/tigase.xml file and restart the server. there is no such file;

I left it as it was. I updated documentation related to Tigase Kernel.

Yes, but while doing so removing obviously non-existent things makes sense? Especially that DLS is third configuration mechanism from "tigase.xml"…

OK, I removed it. But whole documentation of Tigase XMPP Server requires clean up, not only this part.

Yes, I know. I think %Daniel is slowly doing it.

** should we still see calls to .setProperties() (without causing warning) in the logs?

Yes, there are a few places in which we call setProperties() and getDefaults() for backward compatibility. If I'm correct calls of methods marked as @Deprecated are not logged as warnings.

They are:

[...]

At the very least documentation could describe them as deprecated and that usage should be avoided.

I've updated components to use @ConfigField and beans instead of getDefaults() and setProperties() so now it should be fine. No calls to getDefaults() and setProperties() any more.

To do that I needed to change configuration of statistics archivers/loggers, so I updated documentation as well.

%andrzej.wojcik - lgtm (looks good to me)

Afterwards you can assign it to Daniel to fix:

** service-disco-test-comp-admin-300 -- image is not showing up (I guess it's a result of Daniel's merging all docs and then separating them again?);

I have no idea. I left it as it was there. I just updated descriptions related to component implementation and Tigase Kernel.

I'm assigning this to %wojtek to review changes related to @StatisticsCollector@, it's archivers, etc.

Afterwards, if it will finally be ok, assign task to Daniel to fix issue mentioned above.

Dan, could you proceed with the fixes mentioned above?

Daniel Wisnewski commented 8 years ago

Fixed image links, looks like it was just with Dev guide and not all guides as I had thought.

Andrzej Wójcik (Tigase) commented 8 years ago

I wanted to check this so we could close this task but currently there is no documentation for 7.2.0 (except of JavaDoc) available at @docs.tigase.org@.

Daniel, do you know what is cause of this issue? If not then maybe assign this task to %wojtek so he will check it, as it may be some issue with copying of generated documentation to location used by docs.tigase.org to server documentation files.

Daniel Wisnewski commented 8 years ago

Console output shows documentation is built, I think it's to do with the website configuration scraping the wrong directory and finding nothing. Wojciech might have some insight to this.

wojciech.kapcia@tigase.net commented 8 years ago

Daniel Wisnewski wrote:

Console output shows documentation is built, I think it's to do with the website configuration scraping the wrong directory and finding nothing. Wojciech might have some insight to this.

http://build.tigase.org/jenkins/job/tigase-server-distribution/1183/consoleText

Maybe, but probably paths are crooked because I simply copy everything from tigase-server/distribution-docs end it's empty in jenkins machine:

jenkins@build:~/jobs/tigase-server-distribution/workspace$ ls -lah
total 48K
drwxr-xr-x  9 jenkins jenkins 4.0K Apr  1 01:12 .
drwxr-xr-x  6 jenkins jenkins 4.0K Apr  1 01:34 ..
drwxr-xr-x  5 jenkins jenkins 4.0K Apr  1 01:33 distribution
drwxr-xr-x  5 jenkins jenkins 4.0K Apr  1 01:25 distribution-docs
drwxr-xr-x  2 jenkins jenkins 4.0K Apr  1 01:33 distribution-packages
drwxr-xr-x  4 jenkins jenkins 4.0K Apr  1 01:14 documentation
drwxr-xr-x  8 jenkins jenkins 4.0K Apr  1 01:34 .git
-rw-r--r--  1 jenkins jenkins 1.2K Apr  1 01:10 .gitignore
-rw-r--r--  1 jenkins jenkins 6.9K Apr  1 01:10 pom.xml
drwxr-xr-x 10 jenkins jenkins 4.0K Apr  1 01:10 server
drwxr-xr-x  2 jenkins jenkins 4.0K Apr  1 01:10 target
jenkins@build:~/jobs/tigase-server-distribution/workspace$ ls -lah distribution-docs/
total 20K
drwxr-xr-x 5 jenkins jenkins 4.0K Apr  1 01:25 .
drwxr-xr-x 9 jenkins jenkins 4.0K Apr  1 01:12 ..
drwxr-xr-x 2 jenkins jenkins 4.0K Apr  1 01:26 Development_Guide
drwxr-xr-x 4 jenkins jenkins 4.0K Apr  1 01:12 javadoc
drwxr-xr-x 2 jenkins jenkins 4.0K Apr  1 01:25 User_Guide
jenkins@build:~/jobs/tigase-server-distribution/workspace$ ls -lah distribution-docs/Development_Guide/
total 8.0K
drwxr-xr-x 2 jenkins jenkins 4.0K Apr  1 01:26 .
drwxr-xr-x 5 jenkins jenkins 4.0K Apr  1 01:25 ..
jenkins@build:~/jobs/tigase-server-distribution/workspace$ ls -lah distribution-docs/User_Guide/
total 8.0K
drwxr-xr-x 2 jenkins jenkins 4.0K Apr  1 01:25 .
drwxr-xr-x 5 jenkins jenkins 4.0K Apr  1 01:25 ..
jenkins@build:~/jobs/tigase-server-distribution/workspace$ ls -lah distribution-docs/javadoc/
total 4.4M
drwxr-xr-x  4 jenkins jenkins 4.0K Apr  1 01:12 .
drwxr-xr-x  5 jenkins jenkins 4.0K Apr  1 01:25 ..
-rw-r--r--  1 jenkins jenkins 124K Apr  1 01:12 allclasses-frame.html
-rw-r--r--  1 jenkins jenkins 107K Apr  1 01:12 allclasses-noframe.html
-rw-r--r--  1 jenkins jenkins 636K Apr  1 01:12 constant-values.html
-rw-r--r--  1 jenkins jenkins  51K Apr  1 01:12 deprecated-list.html
drwxr-xr-x  3 jenkins jenkins 4.0K Apr  1 01:12 gnu
-rw-r--r--  1 jenkins jenkins 8.9K Apr  1 01:12 help-doc.html
-rw-r--r--  1 jenkins jenkins 3.1M Apr  1 01:12 index-all.html
-rw-r--r--  1 jenkins jenkins 2.9K Apr  1 01:12 index.html
-rw-r--r--  1 jenkins jenkins 9.4K Apr  1 01:12 overview-frame.html
-rw-r--r--  1 jenkins jenkins  18K Apr  1 01:12 overview-summary.html
-rw-r--r--  1 jenkins jenkins 254K Apr  1 01:12 overview-tree.html
-rw-r--r--  1 jenkins jenkins 1.7K Apr  1 01:12 package-list
-rw-r--r--  1 jenkins jenkins  827 Apr  1 01:12 script.js
-rw-r--r--  1 jenkins jenkins  49K Apr  1 01:12 serialized-form.html
-rw-r--r--  1 jenkins jenkins  13K Apr  1 01:12 stylesheet.css
drwxr-xr-x 28 jenkins jenkins 4.0K Apr  1 01:12 tigase
jenkins@build:~/jobs/tigase-server-distribution/workspace$

Hence only names are copied which results in empty, named blocks.

It looks that for some reason you are triggering clean after all building:

[INFO] --- maven-clean-plugin:2.6:clean (Remove docs) @ tigase-server-docs ---
[INFO] Deleting /var/lib/jenkins/jobs/tigase-server-distribution/workspace/distribution-docs/User_Guide (includes = [**/*], excludes = [])
[INFO] Deleting /var/lib/jenkins/jobs/tigase-server-distribution/workspace/documentation/asciidoc/text/components (includes = [**/*], excludes = [])
[INFO] 

which simply deletes all results.

Most likely a result of changes in: #5058 leaving on me and setting as blocked by aforementioned issue.

wojciech.kapcia@tigase.net commented 8 years ago

Andrzej Wójcik wrote:

I wanted to check this so we could close this task but currently there is no documentation for 7.2.0 (except of JavaDoc) available at @docs.tigase.org@.

%andrzej.wojcik - I've checked the guides and images are there hence closing the issue.

wojciech.kapcia@tigase.net commented 8 years ago

Eric, can you check why it's impossible to close this issue?

Eric Dziewa commented 8 years ago

This is really strange, the option of closed isn't present. This has happened in the past. I've closed it in the DB.

mysql> update issues set status_id = 5 where id = 4890;
Query OK, 1 row affected (0.01 sec)
Rows matched: 1  Changed: 1  Warnings: 0
issue 1 of 1
Type
Task
Priority
Major
Assignee
RedmineID
4890
Version
tigase-server-8.0.0
Spent time
94h 20m
Issue Votes (0)
Watchers (0)
Reference
tigase/_server/server-core#756
Please wait...
Page is in error, reload to recover