search

iluwatar / java-design-patterns

Design patterns implemented in Java
https://java-design-patterns.com
Other
89.29k stars 26.41k forks source link

The tool to make the class diagrams should be IDE independent #190

Closed iluwatar closed 6 years ago

iluwatar commented 9 years ago

Not everybody uses Eclipse, which is a requirement for the current tool ObjectAid UML Explorer.

iluwatar commented 9 years ago

I'm planning to auto-generate the class diagrams from the source code.

bernardosulzbach commented 9 years ago

I would like to see this done.

iluwatar commented 9 years ago

I'll give it a shot at https://github.com/iluwatar/uml-reverse-mapper

npathai commented 9 years ago

:+1:

iluwatar commented 8 years ago

It is a work in progress but I've put it to Maven Central with version 1.0.0. I've attached the plugin to JDP project in urm branch. Here's some output it has generated.

urm dot

urm dot

urm dot

urm dot

urm dot

urm dot

npathai commented 8 years ago

@iluwatar It looks good but still a lot of work to be done. I was really thinking whether its a pressing issue currently. I agree that not everybody uses eclipse but its a viable option for now. We can in parallel keep working on urm tool to create a free alternative that is usable. Once we are done with that we can again revisit this issue. Till then what we can do is keep the class diagram an optional clause in PR and we can take the burden of generating the class diagram.

I think we can also consider paid tools like https://www.genmymodel.com, which yes are paid but provide a good alternative. Core team can have paid access to the tool. It generates good diagrams https://api.genmymodel.com/projects/_WEMoIGDtEeW9D6sWhFfmrA/diagrams/_WqZsgWDtEeWzDrmBaWf_bw/jpeg

Awaiting your response.

gilbertoca commented 8 years ago

Hi, What about this UML tool: DoUML Or this plan text UML tool: PlantUML which can be rendered by github via PlantUML github support

markusmo3 commented 8 years ago

I dont know why this issue has been ignored. I quite like the idea of having things unified! And PlantUML sure does look very promising!

@iluwatar you have this nice UML reverse mapper project. I'm thinking of creating a new "PlantUMLPresenter" for it. With that it should be able to output plantuml code, right?

Because then we could use the PlantUML hosting webserver to draw and host the diagrams. And the two together with some travis magic could be used to autogenerate our uml diagrams :D (i'm in a 'automate evryfin'-mood currently...)

What do you (other) guys think of that?

bernardosulzbach commented 8 years ago

@markusmo3 I am not going to help as I don't have the time, but I cheer for you. It seems a good idea.

iluwatar commented 8 years ago

@markusmo3 I will look into this.

iluwatar commented 8 years ago

@markusmo3 I think your plan could work.

  1. The reverse-uml-mapper generates PlantUML markup files
  2. The PlantUML markup can be further manipulated with IDE plugins or online tools Eclipse IntelliJ NetBeans
  3. Travis build generates the class diagram image from the PlantUML source
markusmo3 commented 8 years ago

@iluwatar Seems like im one step ahead of you :wink: One day i had too much time, so i just started ^^ It's not finished yet but works quite good allready. image

bernardosulzbach commented 8 years ago

@markusmo3 Fly as fuck. I'm just judging appearance, didn't read the attributes and methods, but that is the easiest part to get right as it is programmatically assigned.

Really good.

iluwatar commented 8 years ago

I'm not sure I understood @mafagafogigante 's expression but, woah, to me this looks awesome!

bernardosulzbach commented 8 years ago

@iluwatar That's what I tried to say. It looks very polished, almost as if it was the result of several iterations already.

iluwatar commented 8 years ago

@markusmo3 anything I can help you with?

markusmo3 commented 8 years ago

@iluwatar Sorry i have been away for a long time. I graduated and got a job and to be honest somehow lost a little bit of motivation when i looked at the google analytics of our website. If you are interested in it i could do a little report for it.

I have the code for this sitting somewhere, i just didnt do the finishing touches, i will look into it the next few days.

iluwatar commented 8 years ago

@markusmo3 good to hear from you. Congratulations for your graduation and new job! We can discuss the statistics you mentioned in Gitter.

markusmo3 commented 8 years ago

Hey @iluwatar Im wondering if you could help me with a maven thing here. I have this issue nearly completed in my fork, but i need a way to now assign every subproject of java-design-patterns this jar so that it uses the plugin and thus generates the puml file.

Currently i only know the way of copy-pasting the part in the readme into every single pom.xml, but that is a very tedious task, even automated with bash scripts lots of conflicts arise. Is there a way to only write it once into the parent pom.xml and it being applied in every single subproject?

Reproduction:

Any idea?

iluwatar commented 8 years ago

We could try to move the plugin configuration to the parent java-design-patterns/pom.xml. Specify it as follows:

    <build>
        <plugins>
            <plugin>
                <groupId>com.iluwatar</groupId>
                <artifactId>urm-maven-plugin</artifactId>
                <version>${urm.version}</version>
                <executions>
                    <execution>
                        <phase>process-classes</phase>
                        <goals>
                            <goal>map</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <packages>
                        <param>com.iluwatar</param>
                    </packages>
                </configuration>
            </plugin>               
        </plugins>
    </build>

With this plugin configuration urm.dot is generated for each submodule and it contains all the classes from com.iluwatar package and its subpackages.

markusmo3 commented 8 years ago

todo: Check if all images are good enough to replace the old ones and if yes remove old pictures and replace them with the pumls. Also edit the wiki to reflect the new changes

iluwatar commented 7 years ago

@markusmo3 I'm in the process of verifying the functionality and have some questions and comments. This is the .puml of the Abstract Document pattern.

abstractdocument

iluwatar commented 7 years ago

This is the .puml for Abstract Factory.

abstractfactory

iluwatar commented 7 years ago

For Builder pattern .puml I'm getting syntax error. Do you know what causes this? I've raised issue https://github.com/markusmo3/uml-reverse-mapper/issues/3

iluwatar commented 7 years ago

Is my understanding correct that we would use online tools to generate the images from the .puml files? I'm referring to this script https://github.com/iluwatar/java-design-patterns/blob/master/_scripts/postPumlsToServer.py

I am worried about the performance of the online image generation. For example, I have tried to generate the image from the .puml of the Hexagonal pattern multiple times without succeeding.

markusmo3 commented 7 years ago

Lets clear some things up i guess,

The relation between AbstractDocument and Map is containment, right?

Yep, at least that is the symbol for "inner class" relation ship: It reads something like this "AbstractDocument has the inner class Map" but why it is there i have no idea. Thats why we need reviews. I thought i fixed an issue like that some time ago, maybe it creeped back up again. I'll have to look into that, yes.

This issue was put to the side again and i forgot about it :innocent: i will continue work to at least a state that is reviewable locally.

The relation between Document and AbstractDocument is inheritance, right? AbstractDocument inherits Document. The same relationship is between Document and HasType. However, the line types are different (solid vs dashed). Why is this?

realitzation (dotted) vs inheritance (solid) most resources i looked at did this so i did too.

btw im planning on providing a "legend?" that explains the various different arrow types, colors and characters.

The letters after class names e.g. Document (I), AbstractDocument (A), App (C) mean the type I=Interface, A=Abstract class, C=Class right?

Yep!

What are the relations between App and Army, King and Castle? It's not the same containment as in Abstract Document. Is the relation between Abstract Document and Map composition and the relation here between App and Army aggregation (makes sense)?

Usage! or more formerly called Association (because of the field variable)

I am worried about the performance of the online image generation. For example, I have tried to generate the image from the .puml of the Hexagonal pattern multiple times without succeeding.

Performance isnt really an issue here, at least for now. I hope the plantuml servers do a good job of hosting the images here and if not we can still take action later to combat that (e.g. generate locally, travis magic,... ) It just was the easiest solution at hand to go with plantuml webservers that autoupdate with every code changes. The postPumlsToServer script was only executed once and exists only to archive its usage for the future and thus not intended to be used again. The How2 use plantuml webserver and integrate with website topic is also part of the documentation that i have to add to the wiki yet.

markusmo3 commented 7 years ago

with commit d70bfca the new diagrams should be a lot simpler to review! Just decomment (remove the hashtag #) the reviewmode variable in _config.yml and serve the website locally. The new diagrams are now shown on the respective pattern pages.

Problem that arise when reviewing are problems concerning urm directly, so an issue there or direct messaging me would be appropriate.

Proposed Future Usage on new pattern creation:

  1. When pattern is finished and fully approved by the jdp staff the diagram can be generated from source and finally committed
  2. generate via mvn test for simple one module patterns. For more complex multi module patterns look at how aggregator-microservices, naked-objects or api-gateway solved the problem or just ping markusmo3 for help
  3. commit the generate puml file(s)

  4. go to http://plantuml.com/plantuml/uml and add the following, while filling in the YOUR_PATTERN part. The url should point to your file in the 'raw' format.

    @startuml
!includeurl https://raw.githubusercontent.com/iluwatar/java-design-patterns/master/YOUR_PATTERN/etc/YOUR_PATTERN.urm.puml
@enduml
  5. submit the form, if successful the diagram should be displayed correctly, if not the error message should be display. Also review the diagram if everything is displayed correctly.

  6. copy the id from the url

    http://plantuml.com/plantuml/uml/HERE_IS_THE_PUML_ID
  7. add the pumlid front matter variable with the in step 6. retrieved ID (example)
iluwatar commented 7 years ago

The relation between AbstractDocument and Map is containment, right?

Yep, at least that is the symbol for "inner class" relation ship: It reads something like this "AbstractDocument has the inner class Map" but why it is there i have no idea. Thats why we need reviews. I thought i fixed an issue like that some time ago, maybe it creeped back up again. I'll have to look into that, yes.

This issue was put to the side again and i forgot about it :innocent: i will continue work to at least a state that is reviewable locally.

I've created issue https://github.com/markusmo3/uml-reverse-mapper/issues/5

iluwatar commented 7 years ago

with commit d70bfca the new diagrams should be a lot simpler to review! Just decomment (remove the hashtag #) the reviewmode variable in _config.yml and serve the website locally. The new diagrams are now shown on the respective pattern pages.

Problem that arise when reviewing are problems concerning urm directly, so an issue there or direct messaging me would be appropriate.

I will try this and review the diagrams.

iluwatar commented 7 years ago

@markusmo3 I went through the diagrams and this issue https://github.com/markusmo3/uml-reverse-mapper/issues/7 seems to reproduce multiple times. AFAIK all the issues are on the list now https://github.com/markusmo3/uml-reverse-mapper/issues

iluwatar commented 7 years ago

Proposed Future Usage on new pattern creation:

  1. When pattern is finished and fully approved by the jdp staff the diagram can be generated from source and finally committed
  2. generate via mvn test for simple one module patterns. For more complex multi module patterns look at how aggregator-microservices, naked-objects or api-gateway solved the problem or just ping markusmo3 for help
  3. commit the generate puml file(s)

  4. go to http://plantuml.com/plantuml/uml and add the following, while filling in the YOUR_PATTERN part. The url should point to your file in the 'raw' format.

    @startuml
!includeurl https://raw.githubusercontent.com/iluwatar/java-design-patterns/master/YOUR_PATTERN/etc/YOUR_PATTERN.urm.puml
@enduml
  5. submit the form, if successful the diagram should be displayed correctly, if not the error message should be display. Also review the diagram if everything is displayed correctly.

  6. copy the id from the url

    http://plantuml.com/plantuml/uml/HERE_IS_THE_PUML_ID
  7. add the pumlid front matter variable with the in step 6. retrieved ID (example)

The process looks generally fine. The first step says that the diagram can be committed only when the pull request has been approved. I think this limitation should be removed and diagrams should be submitted as part of the pull request. In step 2 generation via mvn test feels hackish. Maybe we can map another lifecycle phase into diagram generation? In steps 4-7 I see that we are going to serve the diagram from the PlantUML online tool? Another option would be to use the generated image files.

iluwatar commented 7 years ago

@markusmo3 the step 2 can be accomplished via mvn urm:map and I think we should recommend using that. See https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html

markusmo3 commented 7 years ago

Thanks for your help on this point here @iluwatar Unfortunately my Desktop PC isnt available at the moment, i can organise and think through some stuff but not code :/

The limitation can be removed, if you'd like to review the diagram early in the pull request. I used maven test to also ensure the user has successful tests, but thats just a personal opinion. I have no problem changing it to mvn urm:map.

The Steps 4-7 represent the interaction with the plantuml server yes. This is something i want to enforce and not only make available to use. The server is autoupdating depending on the puml without any steps to be taken by the user and it also removes the redundancy of having the rendered image on disk (You also dont cache websites with screenshots)

But this system could be changed, if we find out it isnt really feasible, to a jekyll-side plugin. This would mean the whole build process would have to be revamped though, so im holding back on that one,

iluwatar commented 7 years ago

@markusmo3 the issue list https://github.com/markusmo3/uml-reverse-mapper/issues looks better and if I understood correctly the most critical issue https://github.com/markusmo3/uml-reverse-mapper/issues/7 has been fixed? Maybe we are close to production use already or what do you think?

markusmo3 commented 7 years ago

@iluwatar yes i have not noticed major issues anymore.

Just decomment (remove the hashtag #) the reviewmode variable in _config.yml and serve the website locally. The new diagrams are now shown on the respective pattern pages.

After a review we could decide to fully switch to puml. Then ill do all the tutorial writing in the wiki and commit the changes to the codebase.

iluwatar commented 7 years ago

I regenerated all the pumls and reviewed the diagrams.

malekkadri commented 2 years ago

check https://github.com/iluwatar/uml-reverse-mapper