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 :)
Related
I have created two micro-services using java. I need to make a REST api call from service A to service B. The data sent will be in JSON format. Using jax-rs I need to create entity class in both the service.
Since both the entity class be same in both the projects. Do i
Create an common jar and use is for all my entity/domain objects? Does this make my microservice more tightly coupled?
Do i create the same class in both the microservice projects? This will just mean repeating the work in both the projects?
Is there a better way to communicate between the sevices?
In terms of having your two micro services independent and having them also independent in the future I would also duplicate the code. We had the exact same situation before. Several microservices seem to use some "common" classes that can be put to a seperate jar.
In the end we had following situation:
several (5+) services using the same JAR
turned out that classes that we thought are the same, seemed to have slightly different semantics in different services
a change on one of the classes more or less forced us to have a release on every microservice, when it came to releasing (no independency here anymore)
developers tend to see "common" behavior everywhere, so you most likely end up with some "Helper/Utility" classes there as well which is in the meanwhile considered a code smell in OOP
Long story short, in the meanwhile we switched to having the code duplicated, which gives us the freedom to handle our mircoservices really independently, as we only need to stick to the service contract. What happens internally is fully up to the service and we don't have to release all services in the end of an iteration. I'm not saying that the other option is wrong, but it turned out that it was not suitable for us. If you really see common classes between two services and you are sure you don't mess your common library up with other crap, your save to go.
EDIT
Maybe as follow up, we had the same discussion in regards of tests (unit and integration) having share test code in some common classes. In the end this was hell, as every slight change in code or acceptance criteria made 50% of tests fail. Meanwhile our strategy is to not share anything on test level and have everything right at the tests place. By that you are super fast in eliminating or changing tests. In the end the lesson for us was to keep business code as clean and elegante as suitable and the test code in a way to give us the least headache possible.
Edit2
Meanwhile, we define all our REST interface with open api specifications and create the actual DTO objects that are exchanged via the maven plugin openapi-generator. The spec resides in the project that implements the interface and it is published to artifactory. The project implementing the client pulls it and creates DTOs based on that. By that, you have a single point of truth and no need to write DTO boilerplate code.
I'd say it depends on the situation. If you use a shared package, this will introduce a coupling between the two projects. This makes sense, if both of the project build up on the same data classes and therefore will have the same dto objects to work with. Ideally you would have your own nexus which simplifies the usage of the shared artefact.
Otherwise, if only a few classes are redundant I probably would implement it in each sevice separately, which decouples them too.
I am afraid that you need to decide which one the right solution is for your project.
This is common situation where we as developer gets confused. I would suggest to have a common jar(shared) which can be used in both micro services (A and B). It is nothing but sharing a third resource as we use third-party libraries.
In my current project we were in the same situation and we found the best approach to have separate shared libraries(api-shared as name) and consuming it as jar in different micro-services.
In your second approach you ended up with redundant code and also difficult to maintain. Lets say if you have any changes in entity then you have to change in both the entities which is not quite a good way to synchronize the thing.
All in all I would suggest you to use shared jar for both micro services.
Regards
Techno
Is there are any rule of thumb that relates to whether your package structure should allow access of a class from another class in a sibling package.
An example I have a class that represents a Login page:
project.page.login.LoginPage
And a class that represents an Account home page:
project.page.account.AccountHome
Both pages access the std chrome for the project (Header, Footer, Menu stuff and BasePage), is it better to put thoses classes in a sibling package e.g. project.page.chrome
project.page.chrome.BasePage
project.page.chrome.Menu
project.page.chrome.Footer
project.page.chrome.Header
or in the parent package:
project.page
e.g.
project.page.BasePage
project.page.chrome.Menu
etc
I know that this is a stylistic rule of thumb question, which in a way is subjective.
What I wish to know is if there is a commonly accepted rule for this sort of thing. And if so what is the reasoning behind what are the problems or benefits associated with each approach.
Further to Vampire's answer.
My question is not whether you can reference classes from one sibling package to another. It's whether you should and what are the reasons (either way).
There are maybe not exact rules but some guidelines. Link to answer to another similar question Since this answer appears on SO, pasting only the link here. Reading the Uncle Bob articles may give you some pointers.
There is no conventional way to name your packages or grouping your classes in packages. But most of the time people tend to follow the standard Java APIs, and adopted the style from those.
(to name a few)
For e.g.: util, common, basic
you can use this but the best way is to review your specification and make it the most possibly readable and extendable.
the best advice I can give you is learn the rules then forget them to make yours
There is no such thing as a parent- or child-package. Each package in Java is completely stand-alone. Having them named hierarchically and stored like that in the filesystem is just a convention, but technically, those packages are all absolutely non-related stand-alone packages.
It is totally up to you how you like to organize your source-code in packages.
Package allows to combine the related classes/packages together with proper abstraction.
Technically, in Java there is no rule that sibling packages should allow class access from each other.
From design approach and good practices point of view, it is advised to group the classes/packages in a structured and intuitive way.
For eg.,
project.page
project.page.login
project.page.chrome
project.page.account
This facilitates in modularizing and unit testing of the application. Also, proper package hierarchy helps in quick debugging of the application using tools like log4j.
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!
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)
I'm working on a java SE 1.5+ swing application, in conjunction with others. I'm wondering what the best way of managing string resources is. I understand the principles behind resource bundles etc. I'd like to avoid having one property file for every class that needs a string, as this seems a bit of overkill. Especially when you have a lot of classes that may only make a single reference to a string (say in an error handler). On the other hand it makes it easier when collaborating with others as you reduce the risk of merge conflicts.
It seems particularly cumbersome to have to load resource bundles, every time you need to display simple user feedback, likewise in error handlers, when many classes are involved.
What is the most effective way to manage strings in a fairly large application with hundreds of classes, many of which aren't GUI related, but need to pass informative messages back up to the GUI when exceptions occur.
I'm using NetBeans which generally creates a property file for each GUI class, for all text relating to buttons, labels etc.
What makes you think you have to have a separate properties file for every class? Generally you only need a few (or just one!) properties file (per language, of course).
Just call ResourceBundle.getBundle() with appropriate parameters - you can use the same bundle from multiple classes.
EDIT: Having one set of property files per dialog etc makes it easier to see where any particular string is coming from, but it makes it harder to reuse the same messages etc. Quite where the right balance is will depend on the application.
JSR 296 Swing Application Framework has support for resource management (and it looks like will be part of Java 7). SAF aims to pre-build parts of a Swing app that many people frequently need while encapsulating best practices. You probably don't want to tie to it directly but its worth taking a look at what they do to see whether it gives you some ideas. If I recall, they use cascading resource bundles with well-defined naming conventions. The latter means you know where to look and the former means that you can reuse properties across some portion of your package hierarchy.
Many JSR 296 resources collected here.
This may be naive, but what about storing them in a database, either embedded or external? This might simplify management, and changing languages more configurable.
I'm going to implement something similar to Launchpad's translation platform this year:
https://launchpad.net/+tour/translation
In a nutshell:
Concurrent translation
Phrase suggestions based on previously-entered phrases
Policies, e.g. Partly restricted and structured: anyone can suggest translations, while trusted community members review and approve new work
UPDATE
Of course, this builds on top of ResourceBundle etc, but is a nice way to manage all them strings ;-)