Develop Reference

How to meaningful document an actor design

I'm pretty new to akka/actor systems and try to understand code which a colleague has written.
Doing this, I ask myself what kind of documentation would be helpful to get a faster understanding of the implemented "actor system".
As far as i understand so far, you need to understand at least two different perspective of the systems in order to understand it.
The first is the static "creation hierarchy" which mainly defines the child-parent relationship between actors.
The second is the dynamic "message/event flow" which mainly defines the exchanged messages between the actors. As a special case this one also includes realised finite state machines.
So, i wonder if there are common best practices on how to document an actor system:
What kind of views should be documented?
Are there recommended ways on how to structure the code (for instance reflecting the parent-child relation as package structure)?
Naming conventions?
Tools that are able to parse the code and provide some documentation?
...

As I'm yet unable to comment, I'd at least like to point you to akka-viz for the purpose of visualization.
I was also wondering recently about the package structure... and if one should somehow depict the actor hierarchy this way. I then went on and applied a DDD view where actors are nothing but services acting on entities. This doesn't put an emphasis on the implementation detail akka when trying to understand what the application does. The latter being what the package structure should enable people to do.
Would also be interested in a best practice though if there is one :)

Android App Architecture : How should the packages be formed?

I am new to android programming. I often see that programmers create packages as collection of activities, fragments, adapters, etc. To me it seems more intuitive to put all java code required for an activity/screen in one place. For example: For home screen, I will keep the activity, fragments, adapters, custom views, etc all at one place.
Is there is any definite reason the the general practice or is it just a traditional practice ?

This has to do with creating components, reusable objects and code maintenance in a codebase as it grows. Your approach will work for a small application, and there is no rule against it. However, generally creating package/file structures according to the recommended and common approaches makes it easier to make modifications to code and work with others on the same project. Consider the following:
If you have many Activities spread across many packages or folders, then someone tasked with changing the UI will have to traverse those packages. That makes it difficult to identify UI patterns that could be used across Activities and even harder to use those patterns, since you will need to implement them in each package/folder.
This also creates a problem seeing less obvious patterns in non-UI components like data object models, view controllers, etc. For example, if you need a "user" object in two different Activities do you create 2 different objects? This is not reusable code.
So let's say you decide to reuse the "user" object so that you only have 1 class. Then do you sub-class in the other packages that need it in order to follow your pattern? Then if one UI element needs a new method, do you implement it in just that place? Or the base object?
Or do you make the "user" object public and reference it from other packages/folders? If this is your answer then you will begin to create objects in places based on the evolution of the code, instead of based on logic or ease of maintenance. Among other things, this makes it very difficult to train a new person on "where everything is" in your codebase. The "user" object will sit in one place, and then the "user account" object ends up where it is first needed, but not likely to be with the "user" object.
As a project grows to hundreds of classes, I think it is obvious that this approach becomes unmanageable for many applications. Classes will appear in packages based on the UI requirement, not based on the function it performs. Maintaining them becomes challenging.
For example in the case of Lollipop to Marshmallow, Apache http became deprecated. If you had this dependency scattered throughout your project, then you will be looking in a lot of places at how to handle this change. On a small project that might be fine, but on a larger project if you try to do this while other development is taking place, this can become a real mess since you are now modifying across many packages and folders instead of in only a few locations.
If, however, you have a Data Access Layer or Model Layer components that encapsulate the behavior in one or several folders, then the scope of your changes is easier to see to those around you. When you merge your changes into the project, it is easy for the people you work with to know if other components were impacted.
So while it is not necessary to follow these guidelines (especially for small projects), as a project grows and several or many people become involved in the development, you will see variations but the general practice is to group by purpose or function rather than group by UI / visual component. If you start off with some of this in place, you will have less work later to deal with the change. (However, starting with too much structural support early in a project can put the project at risk of never being completed...)
Several answers provides links to the guidelines. I hope this answer helps to explain why those guidelines exist, which I believe is at the heart of your question.

Is there is any definite reason the the general practice or is it just
a traditional practice ?
Yes. In my current application I have over 50 custom UI views and a few activities. At least 10 singleton controller and a lot of database model. So to not lost in the project, I'm using a tidy structure like this:
Activity
Adapter
Controller
Native
Model
-Database
-Rest
Ui
I suggest you to use this structure.

There are no official rules, well maybe best practices which I have not in mind.
I so we get now a opinion based answer:
I use the package names for grouping classes to a logical topic like adapters, activities, etc.
If you want another structure do it like you want, just it could confuse other devs.
Keep in mind that the package name should be unique so you should use a prefix like a domain you own or you are allowed to use (in reversed order of cause).
Check also this link where are some more ideas pointed out: http://www.javapractices.com/topic/TopicAction.do?Id=205
The first question in building an application is "How do I divide it up into packages?". For typical business applications, there seems to be two ways of answering this question.
Package By Feature
Package-by-feature uses packages to reflect the feature set. It tries to place all items related to a single feature (and only that feature) into a single directory/package. This results in packages with high cohesion and high modularity, and with minimal coupling between packages. Items that work closely together are placed next to each other. They aren't spread out all over the application. It's also interesting to note that, in some cases, deleting a feature can reduce to a single operation - deleting a directory. (Deletion operations might be thought of as a good test for maximum modularity: an item has maximum modularity only if it can be deleted in a single operation.)

Normally the activities are places in the main package and fragments, adapters, utils, models in their own packages like fragments in fragments packages and ISODateParser class could go into utils package.
You can find more about it in the Android Best Practices guide which contains best practices for android.
The guidelines about which classes should be placed under which packages are discussed under the Java packages architecture heading in the guide.
Hope it Helps!

How to refactor procedural start-up code?

I have a class (Android Activity) which handles start-up of my application. The application has some pretty complex start-up rules. Right now it looks like a bunch of spaghetti and I'm looking for strategies for refactoring it.
It's honestly such a mess I'm having problems hacking it down to provides pseudo code. In general there are some rules for start-up that are basically codified in logic:
Steps:
Check for error on last exit and flush local cache if necessary
Download settings file
Parse settings and save settings to local native format
Using the values in settings, do a bunch of 'house keeping'
Using a value in settings, download core data component A
Parse component A and load up local cache
During this logic, its also updating the user interface. All of this is handled in a zig-zagging, single monolithic class. Its very long, its got a bunch of dependencies, the logic is very hard to follow and it seems to touch way too many parts of the application.
Is there a strategy or framework that can be used to break up procedural start-up code?

Hmmm. Based on your steps, I see various different "concerns":
Reading and saving settings.
Downloading settings and components (not sure what a "component" is here) from the server.
Reading and instantiating components.
Flush and read cache.
Housekeeping (not really sure what this all entails).
UI updates (not really sure what this requires either).
You might try splitting up the code into various objects along the lines of the above, for example:
SettingsReader
ServerCommunicationManager (?)
ComponentReader
Cache
Not sure about 5 and 6, since I don't have much to go on there.
Regarding frameworks, well, there are various ones such as the previously mentioned Roboguice, that can help with dependency injection. Those may come in handy, or it may be easier just to do this by hand. I think that before you consider dependency injection, though, you need to untangle the code. All that dependency injection frameworks do is to initialize your objects for you -- you have to make sure that the objects make sense first.

Without any more details, the only suggestion that I can think of is to group the various steps behind well structured functions which do one thing and one thing only.
Your 6 steps look to be a good start for the 6 functions your init function should have. If #2 was synchronous (I doubt it), I would merge #2, #3 into a getSettings function.

How to Manage Client Specific Configuration

For a product that is used by multiple clients where different clients ask for different customizations both user interface wise and functionality wise, how to accommodate those changes without getting the code cluttered with client specific code?
Are there any frameworks(for any programming language) that help with this?
To add more detail the UI is web based and written using JSP.

This is one of the most difficult business requirement to manage different versions of same app, so do not expect open frameworks for that case, however each company involved develops its own system for sth like that.
As for business logic modifications, you would benefit for strong interfacing and IoC (such as Spring). You would override the services for your specific case and change the required methods, then inject into IoC the modified version of the service.
As for UI, it's more difficult because you've chosen JSP, which has little flexibility. When you'd be programming in Swing or GWT, than you could do UI modification same way - override needed UI classes, change them, inject modified versions. With JSP - propably there will be lot of modifications to .jsp files in your customized version.
Now the change modification/bug fixing - there is fully usage of version controll system. Of course, your customer-specific versions are branches, while main, standard version is trunk. Bug fixes are made to trunk, then merged to customer-specific branches. With interfacing/overriding implementations most of the merges would be the easy way, however, with JSP, I would expect conflicts to be often...
Generally, code changes merge easier than anything XML-based.

How about simple OOP? Set up a realistic interface/base class and depending on some sort of configuration, instantiate either child class A or B, depending on the client. It's hard to provide more detail for a language-agnostic question like this, but I think it's very realistic.

One solution to this problem, common in the Win32/.NET world, is to move client-specific "code" into resource files. Many .NET projects (.NET has built-in support for this pattern through the System.Resources namespace) use this pattern for internationalization, by placing the UI strings into one file per language, and then loading UI strings from the appropriate file at runtime.
How does this pattern apply to a JSP application? Well, here you can keep one resources file per client (or, instead of files, use a database), and load the user-specific customizations from the resources file whenever you serve a page.
Say for example that your biggest customer wants to have their logo overlaid on some part of each webpage in your site. Your page could load the CustomerLogo property, and use that as the src attribute for the HTML image at that part of the page. If you are serving the page to the important customer, you load the URL "/static/images/importantCustomerLogo.png," and otherwise you fall back to the default resources file, which specifies the URL "/static/images/logo.png."
This way, you can abstract out the code for loading properties into one or two Java files, and just use those properties throughout the website. The only part of your codebase that is customer-specific will be the set of resources files, and those can be in a clean XML format that is easy to read and modify. The upshot is that people who didn't develop the application in the first place can modify XML without having to read the code first, so you won't have to maintain the resources files - the sales department can do that job for you.

GWT does this out of the box via a feature called deferred binding
When compiling a GWT application the compiler actually generates different versions of the code targeted for each different browsers. this is done automatically out of the box with the GWT components taking care of the different browser gory details.
This feature can be expanded to product arbitrary compilations based on custom properties. here is a simplified example: assume you have different view definitions for a normal and a detailed view
public abstract class AbstractView { ....}
public abstract class NormalView extends AbstractView { ... }
public abstract class DetailedView extends AbstractView { ....}
you can create a module definition that will generate two different versions, one using the NormalView class the other using the DetailedView (in your gwt.xml file)
<define-property name="customMode" values="normal,detailed" />
<replace-with class="com.example.NormalView">
<when-type-is class="com.example.AbstractView" />
<when-property-is name="customMode" value="normal" />
</replace-with>
<replace-with class="com.example.DetailedView">
<when-type-is class="com.example.AbstractView" />
<when-property-is name="customMode" value="detailed" />
</replace-with>
using
AbstractView view = GWT.create(AbstractView.class);
will provide the appropriate instance at runtime.
It's up to you to encapsulate your client specific code into specific classes, and to expose common interfaces for the different implementations.
You will also need to select the appropriate compiled version according to the client currently viewing (you can use jsp for this.)
please don't take the code samples above as tested, there might be problems with the syntax, it is just intended to convey the general idea
A JSP backend is an ideal hosting environment for a GWT app, you will be able to take advantage of the requestfactory mechanism for easy communication between client and server.
obviously there is a learning curve here, IMO the official documentation is a good place to start.

I guess that you may try to read OSGi related articles (or books)...This platform would give you a very pragmatic answer to your modularity issues.It's especially designed to be able to handle different modules living all together with dependencies and versioning.
As mentionned early in an answer , dependency injection through the OSGi Declarative Services is a very valuable alternative to Spring , with dynamic capabilities.. Deploying a bundle providing a service and your references will be updated automatically , dropping it and they will be refreshed too...
Have a look to this technology and ask some questions after ?
Regards
jerome

When to use JAF activation

I wonder if I should use it, in this example. I'm reading files, and I need to store one parameter with that file.
According to this parameter I'm bundling files together and sending them over the wire.
I came accross jaf activation framework, and I'm not sure if it is appropriate to use it in such simple example.(store 'file' into DataHandler with this parameter or to make me simple holder). Of course I don't know if requirments can change in the future, and I will need more.
What do you think about it?
My impression is that it's too much, it's difficult to get proper sources. But on the other hand it has what I need.
The question could be more general as well, should I use framework which can do a lot more, if I need something really simple and I can code it quickly?
thanks in advance

To answer your more general question, I would most often make use of frameworks wherever possible.
It's always possible that you're going to want more functionality in that area. If you're using the framework then great. Otherwise you have to back out and rewrite. Or maintain two different implementations.
Frameworks have been debugged/tested etc. and will handle the edge cases. Often what you think of as being trivial ends up more complicated than you first thought.
Don't forget that due to how class loading works, the JVM will only load the classes you require. Consequently you're only affecting the size of deployment of your application, not the runtime size (by referencing a sizable jar)