Use cases

[GOKHAN DILEK]

Dear Uncle Bob,

I would like to thank you for opening my eyes in the world of software development.

Clean code series are the best and I think anyone who is involved with software development should watch them before starting to code today.

I would like to give you some background information in my project.

• There is an external system where the images are stored (Postgres). 
• The external system's frontend and the photo editor was not sufficient enough and looked old school.
• I also needed to let the users attach documents to a photo gallery(which is linked to Google Drive API)
• The old system's frontend was too difficult to modify yet even to compile...

So I started developing a "front end web app" to interface to this external system(wish I was watching the clean code series at this point).

This project involves parsing images from an external system via the JSON API. 

Users also need to login to the system(the credentials are stored in the external system's Postgres parsed via the JSON API similar to parsing images) and filter the images and search for the images.

Images are then opened in a special open source HTML5 photo editor to view and manipulate them.

I am now coupled to apache tomcat web server, coupled to PrimeFaces framework, docx4j library for documents & partially coupled to postgres(although I have a postgres gateway which protects my application if the external database changes) & the user management is done at the external source.

I also have document id references coming from Google Drive API which are then saved back to the Postgres(external db) to a different column in images table.

The system is already in production

And my code is a tangled mess.

Although this is not a huge system, I am worried for feature requests.

I would like to know where I should go from this point.

Is it possible for me to clean this system at this stage? I don't mind deleting it completely. 

Or I would be better of creating a clean architecture following your methodologies - use case driven design.

Below is the business specific rules that I come up with for my application if I was to create a clean architecture.

No dependencies and 100% testable pure code inside out.

DoLogin(user)

SeeImageList(filter) 

CeeateDoc(type)

LockDoc(doc_ID)

ViewImages(image_id)

CreateISOofImage(image_id).

Should these be interfaces or abstract classes?

Please kindly let me know if you have other suggestions - I would really appreciate it.

Thank you and keep up the good work.

[Sebastian Gozin]

I'm not Uncle Bob but you're looking to undertake something I've done.

I would start cleaning the code as you go and pay attention to the things you learned from the cleancoders videos, or the books or other useful sources.
E.g:

• pay attention to architectural boundaries
• pay attention to the SOLID principles
• apply TDD & BDD for all new code
• add tests to legacy code
• abstract away those pesky dependencies on things like the Google Drive API, docx4j, json, etc...
  
• use a build server to:
• test for regressions
• automate deployment

Frankly, it's a lot of work so be patient. You also can't do everything at the same time and you will make mistakes and change your mind from time to time.

So more reason to be patient while you work on things. Just look back from time to time and observe the improvements.

[GOKHAN DILEK]

Hi Sebastian,

Thank your for your reply.

What do you mean by abstracting json?
How can one abstract json?

I thought json was a simple plain data to move back and forward?

And how can you abstract APIs like Google drive? And should I be worried about it?

[Sebastian Gozin]

I mentioned JSON and Google Drive because you referred to them as tools you are using in some way or another.

When you say the system is a tangled mess I suspect there are probably direct dependencies to those 2 API's scattered over the source code.
For example, you might not be able to execute a unit test without having to interface directly with a Google Drive account.

I don't know if this is true it's just something I expect to see in a messy system.

So, when I say abstract it away I mean you could create code which looks a bit like this perhaps? (is this perhaps the "CreateDoc(type) rule you're talking about in your OP?")

library.findAlbumByName("holidays").attachDocument(attachment);

interface PhotoAlbumLibrary {
  PhotoAlbum findAlbumByName(String name);
}

// This holds businessy stuff but attachDocument remains abstracts because you'd implement it with Google Drive below.
abstract class PhotoAlbum {
  abstract void attachDocument(InputStream attachment);
}

// The code below would exist in a different module which you'd link dynamically at runtime.
class GoogleDrivePhotoAlbum extends PhotoAlbum {
  void attachDocument(InputStream attachment) {
    // use google drive API to stream the attachment into the right place
  }
}

As for JSON. I'm thinking you're not passing strings holding JSON structures in them through your code. You're probably using your own data structures.
It's just like with Google Drive that you'd have to write some code to convert your own structures to and from JSON somewhere.
Just try to keep those dependencies inverted so you can use something other than JSON elsewhere if there's need for it.

Anyway,
I got the impression from your OP these are things you already know about.
It just seemed like you felt like you didn't know where to start.

I was trying to suggest you just start and don't lose hope as you slowly improve things.

[GOKHAN DILEK]

    public static File createFile(Photo photo, DocumentTypes documentType) {

        System.out.println("CREATING FILE");

        try {

            File body = new File();

            body.setTitle("Document for " + photo.getPerson_name()

                    + " - PersonID " + photo.getPerson_id()

                    + " - " + ".docx");

            body.setMimeType(GOOGLE_DOCOCUMENT_MIME_TYPE);

            body.setEditable(true);

            Permission owsership = getOwnerShipPermission();

            Permission unlockedFile = getUnlockedFilePermission();

            java.io.File fileContent = null;

            switch (reportType) {

                case DOCUMENT_type1:

                   //create document

                    break;

                case DOCUMENT_type2:

//create document

                    break;

            }

            FileContent mediaContent = new FileContent(MS_WORD_DOCOCUMENT_MIME_TYPE, fileContent);

            File file = driveservice.files().insert(body, mediaContent).execute();

            String fildid = file.getId();

            //driveservice.permissions().insert(fildid, owsership).execute();

            driveservice.permissions().insert(fildid, unlockedFile).execute();

            fileContent.delete();

            return file;

        } catch (IOException ex) {

            ex.printStackTrace();

            return null;

        }

    }

For example, this is how I am creating the file in the GoogleDriveServiceFactory.java. 

I can see the problem with the document types -  there is something wrong with the design...

Regarding the JSON, yes thats exactly what I am doing. I convert them to my data structures.