Project Stage 2

Project Stage 2#

Client Library Interface Specification#

Write a specification of the client library interface (that any UI or testing code would use to test your client implementation; not a single Java interface) in Java code with relevant Javadoc documentation, and a high-level description of the interface in a README.md file. Use the provided GitLab project by forking it and adding files in the comp1140.project.client package within the src folder. As usual, make sure that the comp1110-2026-s2-marker user is added to your fork as a Maintainer, and that your project has the slug comp1140-2026s2-project-stage2.

You can use the ChatClient interface that is already in the provided project, or remove it. You may use additional packages nested within the above package if you so desire.

The client library interface should specify all types and methods that are used in communicating between the client library (which manages the network connection to the server) and any application code that uses the library. Said application code should only need to have a high-level idea of the features that the chat protocol supports, and be able to call methods provided by the library to interact with the server.

Formalities#

You need to push your files on Gitlab by 5pm on Friday, 2 October. No late submissions without extensions will be accepted.

Groups#

You may do this assignment alone or in a group of up to 5 students. All students in a group must be enroled in COMP1140. If you work in a group, you must to produce the files together in one or more live meetings. Everyone in the group is responsible and must understand every line of code and documentation. The purpose of working together is to include more perspectives and thus have a better chance to think of various corner cases, not to divide up work.

To submit as a group, you have to have a draft (does not need to be complete) of your specification and code pushed to GitLab by the week 8 workshop (i.e. Tuesday, 29 September). The draft must feature the names and UIDs of everyone who participated in the creation of it, and specifically list sufficient individual contributions from everyone. Your whole group must come to me before the workshop (modulo excuses due to illness, in which case you need to send me an e-mail before the workshop), and hand me a copy of the draft (either as a print-out or as an e-mailed PDF). I will confirm the groups on the evening on that day. If you do not get a confirmation e-mail for your group by 23:59, Tuesday, 29 September, you must create your own specification and code. You can base the project on your own listed contributions to any group document that was rejected. You are in any case expected to have invested a significant enough amount of thinking time into this to be able to finish the specification and code relatively quickly, even if this happens. Do not wait to start working on this until Tuesday of week 8.

License#

By default, by submitting this assignment, you grant us a license to publish it here in either its original form or with changes made by us, as part of a specification for the rest of the assignment, in the case that your submission gets chosen as the specification. Your contributions will be attributed to you. You may object to either the attribution or the publication, by stating this at the start of your README.md file. In case you object to the publication, your submission will not be eligible to be chosen to form the specification for the rest of the assignment, but will still be marked normally.

If you work as a group, any member of the group may object to attribution or publication, which for attribution is individual, but for publication will affect the whole group’s submission. Discuss any potential objections early on when forming a group. For a group submission, objections for the draft submitted at the week 7 workshop and the final version are separate. You need to include any objections to attribution or publication for the draft version, and anyone can change their opinion on attribution or publication for the final version. In case a member of a group did not object to publication for the draft version but does so for the final version, the group may try to submit a second final version that excludes contributions by that group member since the draft version, which would be eligible for selection and publication; the full group final version would be the one that is marked.

In summary:

• If you don’t want your submission to be used as the standard: Object publication by stating this at the start of your README.md
• If you don’t want your name on the submission if your standard is chosen: Object attribution by stating this at the start of your README.md

Backup and Flexibility#

While we aim to (at least largely) use one of your submitted specifications for the rest of the project, we may decide to use our own. In either case, the specification will not be completely set in stone. As we discover new corner cases or other difficulties, or if we decide to add extensions later on, we may adjust the specification during the course of the project. We invite you to actively participate in workshop discussions and on the Ed Class forum to provide input on any necessary or otherwise desirable changes.

Structure#

Your classes and interfaces should enable a user to make full use of the functionality of the chat protocol, without exposing implementation details of the protocol or the networking infrastructure. For any action that a user asks the library to do, there should be a way for them to discover the result of said action.

You need to clearly document any data invariants, pre- and postconditions of methods, and describe the intended behaviour of the methods. Remember that it is not just you who are going to implement those methods, but also your colleagues and us. And we specifically may be somewhat devious in how we create our own implementation(s) while following everything you specify. It must, however, be possible to actually fully use the funcionality of the chat system while also fully following any restrictions you specify.

You should largely use interfaces. You must specify some particular static method or constructor that should serve as the starting point of using the library. Any implementer will have to implement that code (so you should leave it empty) to set up and return an initial object from which a user can start using the rest of the library’s functionality.

In your README.md, you should document on a high level how your library interface works. You should also specify a few concrete examples of how one would use the library: assuming a suitable implementation of your entry point static method or constructor, a user should now have access to a concrete instance of one of your interfaces, and should be able to write some code in terms of things that you have specified.

As this assignment will mostly come in the form of Java code and comments, it is not straightforward to provide a length restriction. You must keep the interface and its description as short as possible while providing all the necessary detail. Do not make this overly complicated or verbose - we will rate such specification as “poor”. Remember: you and your peers need to be able to implement code based on this and be able to easily understand it. And we need to be able to go through all of them in a reasonably short amount of time. Good specifications are precise and to the point.

Versions#

As a reminder, this is the overview from the chat protocol specification. Your library specification needs to support the features described by your protocol specification, now on the level of Java. Remember that, while both the protocol and the library need to support the same functionality, there does not have to be a 1:1 mapping in individual actions. It is the task of the library to translate between the two anyway.

Version 1 - Basic Chat#

• Clients connect to server and authenticate via username and password hash
• Clients can somehow find out list of users
• Users can send direct messages to other users (and receive said messages)
  • Users may be offline, in which case server stores messages for them and delivers them when they connect via some client
• The protocol should ensure that, given enough time, any user that is currently online and any other user could see the same chat history between them up to the point where the other user was last online (that is, every client should eventually be aware whether sending a message succeeded or not)

Version 2 - Channels#

• Users can create new channels
  • Initially, only the creating user is a member of the new channel
  • Channels exist permanently (though client UIs may offer a feature to hide them)
• Users can add other users to channels of which they are a member
  • Membership is permanent and offers accss to the whole chat history of a channel
• There is a global channel of which every user is a member, they can send to it and see all messages on it
• Messages are sent to specific channels, and have at least an author, a timestamp of when they were sent, and a body of text
  • Direct messages from version 1 may now be seen as particular channels, and there might be multiple channels for direct messages between two people (see Ed forum for options here)

Version 3 - Metadata#

• Channels have a unique identifier, but may also have a name that any user in them can change
• Users may change their display name (though their username for authentication remains unchanged)
• Users may set a status message
• Such metadata changes are propagated to other clients

Version 4 - Receipts#

• Clients send and receive receipts for a message having been delivered to a client, and for a user having read a message

Version 5 - File Transfer#

• Two clients that are simultaneously online may transfer an arbitrary file from one to the other (the data is transferred via the connections between the clients and the server, but the server never stores that data other than to immediately forward it)

Further Discussion#

The above specification is meant to be at a relatively high level, which hopefully leaves you some room to make your own decisions. Some of those you can just make as part of specifying your protocol, but you may encounter questions that warrant broader discussion. If so, please make use of the Ed Discussion forum (there is a category for the project). You should feel absolutely free to discuss any aspect of the project with any of your classmates. In fact, we highly encourage you to do so.

You will still need to write separate reports beyond the maximum group size, and ultimately, you will need to write the implementations of the server, client library, and client UI yourself. But beyond that, please discuss design decisions, corner cases, and other issues freely and openly. We’ll weigh in where necessary, though we hope that many questions can be resolved among you all as a cohort.

Hint: some of you might want to work with a group, but haven’t had an opportunity to form one in the last workshop. The discussion forum may help you there, too.