Jedi Manager (Jedi

Jedi Manager (Jedi_Manager)

Table of Contents

1. Resources
2. General Overview
3. Customer requirements
4. Company requirements
5. Project milestones
6. Submitting final version
7. How to compile the project
8. Evaluation Aspects
9. Sources of “inspiration”

1. Resources

Project templates here.
Notes on how to work in a team.

2. General Overview

Based on your own accumulated experience, SAUCEM Inc. receives a customer request to design an application to manage combatientes Jedis, informally called Jedi_Manager.This application is supported by dynamic data structures, therefore the customer requires an application that allows to insert, remove, and modify Jedis warriors. The customer also requires functionality tha may export and import application data from a file in binary format, Jedi combat, support to corrupt records detections and an autosaving function.

For each Jedi, its corresponding record should include:

A unique Jedi identifier, which should be a integer: int id, that should be greater than 0. This type of identifier is mainly used to identify a Jedi and to perform some actions on it.
Name of the book, represented as an string: char* s_full_name. There are not any limits on length of the name of a Jedi.
Length of the name of a Jedi: int size_name. It corresponds to the size of s_full_name.
The internal characteristics of a Jedi should be stored in a structure called struct points* ptr_points that will contain the following elements:
- Hit points of a Jedi, wich should be an integer: int hit_points. A Jedi with a zero or negative hit_points is dead and cannot participate in any combats.
- Attack points defined as: int attack_array[2]. It is used in the combat to inflict damage to a rival. It contains normal attack defined for an aprentice: T_APPRENTICE=0 or a master: T_MASTER=1.
- Defense points of a Jedi: int defense_array[2]. It is used in the Jedi's combat. It contains apprentice defense points: T_NORMAL=0 or master points: T_MASTER=1.
- Speed of a Jedi: double speed_array[2] . It includes the speed of the apprentice and a master: T_APPRENTICE=0 and T_MASTER=1
- Current level enum level_jedi of the Jedi that can be T_APPRENTICE=0 or T_MASTER=1.

3. Customer requirements

Console application: The application starts from a command console and it is manipulated entirely with the keyboard.
To organice the source code, the main file of the application will be called my_jedi_manager.c and their prototypes are stored in a file called my_jedi_manager.h. You may add further files, if you require them.

After starting, the application shows a main text menu with all possible operations, each of them identified with a different number or letter. If when waiting for the user to type a command, the combination CRTL-D is typed, the application must terminate.

        =========================================
        [*][2017][SAUCEM APPS][JediManager]======
        =========================================
        [1] Exit
        [2] Inserting a Jedi
        [3] Show Jedis
        [4] Show a Jedi with ID
        [5] Modify a Jedi with ID
        [6] Remove a Jedi with ID
        [7] Export Jedi's to a binary file
        [8] Import a Jedi from a binary file
        [9] Jedi combat simulator
        [10] Sort Jedis with hit points
	[11] Jedi autosaving (5 seconds, if it changed)
                      #INFO:   1 times shown this menu

        Type an option:

The operations that the main menu must have are (at least):
1. Exit the program. The application should offer the posibility of asking the user if s/he wants to exiting.
```
Are you sure you want to exist the manager?[y/N]: 
```
2. Insert. This function is in charge of inserting a new book by a command line option. The new element is to be allocated in dynamic memory to be be able to be modified at runtime.
```
	    
	       Inserting a Jedi
                        Give the ID of the Jedi: 1
                        Give the name of the Jedi: Yoda
                        Give hit points: 45

                        Give the attack of an apprentice: 53
                        Give the defense of an apprentice: 70
                        Give the speed of an apprentice: 42,5
                        Give the attack of a master: 400
                        Give the defense of a master: 600
                        Give the speed of a master: 425,0

			Is a master (y/N)?: y
			
```
3. Show a summary. It includes the id of the Jedi followed by the 10 most significative characters of the mane of a Jedi, followed by the hit points, attack, and defense.
```
        ================================
        |  ID|     Name |  HP|Ata.|Def.|
        ================================
        | 1 |   Yoda    |  45|  53|  70|
        ================================   
      
```
4. Show publication info of a Jedi. This option is in charge of showing all information of a Jedi included in the data record. The way to access this information is by means of the identifier (ID) associated to each Jedi.
```
 
        = Full infomation of a Jedi
        = id: 1
        = hp: 45
        = name: Yoda, Master

        = attack of apprentice: 53
        = defense of apprentice: 70
        = speed of apprentice: 42,5
        = attack of master: 400
        = defense of master: 600
	= speed of master: 425,0

	      
```
5. Modification of a Jedi. This option will allow you to modify the records of a Jedi whose ID is provided in the command line. It also includes the posibility of changing the ID of a Jedi.
6. Remove a Jedi from its ID. This menu option is in charge of removing a Jedi reference from the system given an ID provided from the command line. If several Jedis share the same ID, then only the first listed book is removed.
7. Export Jedis to a file. This option is in charge of storing all books stored in memory in persistent storage (i.e. a file) with fwrite. The name of the file will be asked to the user.
8. Import from a file. This option is in charge of getting data store in permanent medium (e.g. a file used in the export option) to store this data in memory using fread. The user should decide in which file are stored Jedis. Data read will be added to the begining of the table, in memory.
9. In the Jedi combat, the user should select two Jedi by Id. If they exit and have hiting points, the combat gets started and runs until one of them dies. In the first, the first Jedi attacks and the second is in defensive action. After that, the second attacks the first. After two turns all Jedis get reduced their hiting points in accordance the damage received. To calculate the damage of apprentice Jedi_1 on a Jedi_2, it is used the following formula: damage=((Jedi_1->speed/Jedi_2->speed)((86+rand()%15)*Jedi_1->attack)/Jedi_2->defense)/10. Depending on the nature of apprentice or master, it is used a proper characterization, as master or as an apprentice.
  
  As an example of a combat, let's assume a Jedi 1 that has hp: 100, attack[T_APPRENTICE]: 10, and defense[T_APPRENTICE]: 10 and a second Jedi named Jedi 2 with hp: 18, attack[T_APPRENTICE]: 5, defense[T_APPRENTICE]: 5, and speed[T_APPRENTICE]:2. With these two Jedis one example of acombat is the following: Jedi 1 attacks with maximum power and damages Jedi 2 with ((2/2)((86+15)*10)/5)/10 =20 hitting points. After that, and assuming a maximum power in the replica, Jedi 2 attacks Jedi 1 with the following damage: ((2/2)((86+15)*5)/10)/10 =5 points. After the combat the updated live of the two Jedis will be Jedi 2: (18-20)=-2 with no choice for new combats and Jedi 1 that losses 5 points with (100-5)=95 points. Since Jedi 2 has a negative life, it cannot continue with its execution.
  
  At the end of a combat, if an apprentice defeats a master, it changes its status to master. Likewise, if a master is defeated by an apprentice, it changes its status to apprentice.
10. Sort Jedis. It sorts according to increasing life points.
11. Activate autosave Jedis. This functionality activates an autosaving system, implemented with a POSIX thread, in charge of saving a modified list to a file called ##auto_jedi_save.dat of all data of Jedis. It will store Once autosaving is activated, it is active until the program finishes.
After selection an operation, additional data may be introduced through the keyboard. When the operation finishes, the main textual menu is shown again and the application waits for a new command from the user. The user may enter Crtl-D to return to the main menu without finishing the operation.
The application must be robust, that is, it should recover with no problems if at some point the user introduces incorrect data (letters when numbers are expected, an empty string, an empty line, an incorrect file name, an empty file, etc.).

Warning!

Although more frequent than desired, in an industrial context sometimes the customer makes adjustments to the specification while the project is being developed. Thus, if such situation arises, the team should treat it normally.

4. Company requirements

Aside from the customer requirement that are related to the finished project, SAUCEM Inc. has its own product development policy oriented toward maintaining an image of a reliable company, and to assure an efficient development cycle. These requirements are:

The project solution must use some type of dynamic data structure.
Solutions using global variables are not allowed. All variable you need will be satisfied using dynamic memory and/or the stack.
```
int global_variable; //Not allowed
int my_function(int input)
{ 
  return input;
}        
```
The code must be divided into files such that similar functions are grouped. Function names have to be chosen to increase code readability and to quickly locate certain functionality. Each function should have a developer (@dev_nia), a tester (@tester_nia), a system integrator (@int_nia), and its corresponding tester (@test_int_nia). The developer and the tester are in charge of the internals of the function, and the integrator and the system team are in charge of the external ecosystem.
```
	//@dev_nia 10000000 @tester_nia 10000002 @int_nia 10000003 @test_int_nia 10000003  
	int funcion(int input)
	  { ...
	
	  }	 
```
All source files (*.c) and definition files (*.h) must have the structure of the templates CFile.templ and CHeaderFile.templ respectively, which you will find in the Templates directory. The top of the file must include a detailed description of the functions and definitions contained in the file. All those fields in the template that have no information should be deleted. For example, if your code has no “macros” then delete that part of the template.

Furthermore, the most complex parts in the code should have a block comment explaining its functionality. Do not include small comments in each line, but blocks at the beginning of a set of steps.
All functions, global variables, #define, structure declaration and enumeration definitions must be documented preceding their definitions with the text in the templates included in the files Function.templ, Variable.templ, Macro.templ, Struct.templ and Enum.templ respectively. In the case of functions, the description of the parameters and the result must be included. The fragment to include with their fields to be completed can be found in the Templates folder of your working directory.
If the symbol DEBUG is defined when compiling, the application shows on the screen debugging messages with the main operations executed.
The code must compile with no error or warning when compiled with the option -Wall in gcc.
The code must be written strictly following the rules described in the following guide.
The application must perform a correct dynamic memory management, that is, no leaks, access to uninitialized portions, incorrect frees, etc.
In the Minutes folder include the minutes for each of the team meetings. These minutes should include the agenda, the team members attending, who did what role and the decisions taken.
The code must be created equally by all team members. We required to have a contribution balanced among the team members. Each team member has to contribute to the project.

5. Project milestones

The project has been divided into several “milestones” to facilitate its execution. A milestone marks the end of a phase and the beginning of another. Project milestones typically have a set of “deliverables” attached to them, which are program fragments, documents or any element related to the project that must be ready to be delivered. The project milestones described here should be taken as a suggestion of how the project should proceed. Your team might not follow these milestones strictly, but this is not important as long as the project work is gradual and the final submission of the product is done. If a team reaches a milestone earlier than scheduled, it should not stop, but continue to the following milestone. The proposed project weekly milestones are:

Milestone 1. Create a document including the description of the modules in which the application will be divided, as well as the required data structures. Each module must include a description of the functionality to be covered and the manipulated data. The team must assign a member as responsible of each module and mention this person in the document. Throughout the project execution, this division must be adjusted as necessary.
Milestone 2. Implementation of functionalities 1 to 3 from the ones given by the customer. Those locations in the application where the required functionality is not ready yet, must include a temporal solution.
Milestone 3. Implementation of the functionality 4 and 6 from the ones given by the customer.
Milestone 4. Implementation of functionalities 7 to 10 from the ones given by the customer.
Milestone 5. Implementation of functionality 11 and final testing.

6. Submitting final version

Via Aula Global.

7. How to compile the project

To compile your project you must add to your compilation command the following options:

gcc -pthread  -g [YOUR OWN FILES]

To avoid to type several times these lines, you must write an bash file in charge of performing the compilation.

8. Evaluation Aspects

The following table shows the guide used to evaluate the project submissions. Those categories that occupy two cells are evaluated with the highest score.

Aspect	Excellent (100%)	Good (75%)	Fair (50%)	Poor (0%)
1 Code compilation with the option `-Wall`	The code compiles with no warning no error.		The code compiles with two warnings.	The code does not compile, or it does with more than two errors.
2 Program tests	The program runs normally and according to the spec.	The program terminates abruptly in one test or does not comply with the specification in one or two aspects.	The program fails two tests or does not comply with the spec in more than two aspects.	The program frequently fails or does not comply with the spec.
3 Memory management	The application runs with no anomaly when analyzed with Valgrind.	Only a leak or an incorrect memory deallocation is detected.	Valgrind detects two anomalies when executing the application.	More than two anomalies are detected when executing the application with Valgrind.
4 Debugging messages	The main steps of the of application print debugging messages when the symbol `DEBUG` is defined.		The application prints few debugging messages.	The program does not contain any debugging messages.
5 Code in multiple files, definitions and prototypes in `.h`	The code is divided in various files and the definitions and prototypes are included in one or more files with extension `.h`.		Either the code is in a single file, or the file with definitions and prototypes is incomplete (or incorrect).	The code is divided arbitrarily and the `.h` file contains incorrect information and is not properly included.
6 Use of file templates and documentation in the header.	All the files follow the template, have all the mandatory fields filled and the documentation in the header is helpful.		One or two of the files do not follow the template, do not have all the mandatory information fields filed, or the documentation in the header is not enough.	More than two files do not follow the template, have some fields empty, or the header documentation is not sufficient.
7 Global variables, structures and function documentation	All the global variables, structures and functions are perfectly documented.	In a file there is a variable, a function or a structure definition with no comments.	There are two files with variables, functions or structure declarations with no documentation.	There are more than two files lacking documentation for functions, structure declaration or global variables.
8 Code Style	All files comply with the requirements of the style guide.		Some of the files do not comply with the requirements of the style guide. Or some of the criteria in the style guide are ignored completely.	The majority of the files are not indented or do not observe the 80 column width limit. Or most of the style guidelines are ignored.
9 The application is intuitive	The user understands with no problems the functions, the data to introduce and how to introduce them.		In general the messages are clear, but in some cases it is not clear what the user has to do.	The user is frequently stalled because the functions are not clearly explained.
10 Meeting Minutes	The team has met frequently (at least once a week) and the minutes reflect their content.		The team did not meet with the desired frequency and/or the minutes do not reflect the real activity.	Minutes are incomplete, or there is a low number of them.
11 . Work evenly distributed among team members.	All team members have evenly uploaded files and created code.		Only part of the team has uploaded files to the repository and created the code.	Only one team member has uploaded files to the repository and created the code.

The criteria are ordered in decreasing significance. Having the first two correct is a requirement to pass the project. If the program does not compile or fails frequently, it is considered unfinished and the score is zero.

9. Sources of “inspiration”

When a project similar to this one is started it is fairly common to obtain information from different sources that contribute to its development. When the project starts and the deadlines are fare away, there are no problems. But when the deadlines are crawling up on you, your decision ability is greatly impaired. The best way to avoid problems is to have a clear idea at all times when those sources are being used reasonably, or could be considered a case of plagiarism. We give you a set of suggestions.

Comment in the aisle, in a classroom, between two classes how are we solving a special aspect of the lab (no problem)
I am studying with a few friends in the library and one of them takes a piece of paper and draws the problem he is having in the project. I also draw in the paper our solution (no problem)
After that conversation, my friend writes to me and says that he/she still has some doubts. I send him/her an email with a more detailed textual description of what we have done (no problem).
I receive another email and he/she still has unclear aspects. I cut and paste a fraction of our code in the email I sent as answer (yes, we got a problem). Easy to detect by the structure of the code. Even if it is a small chunk.
I find a chunk of code in Internet that does what I need, I cut and paste, and after a few adjustments, it works (no problem). Make sure you include a reference in the code as a comment.
(Based on a real story) I work in a company and I showed the project handout to my colleagues. One of them was excited and sends me part of the solution (yes, we have a problem). Easy to detect, each person writes code in a different way, it is highly unlikely that your colleague has the same C level than you. Besides, very likely that colleague wants to brag about solving it and may even tell the professors (it happened already).
(Based on a real history) My best friend landed in a team that does not perform well and is frustrated. He/She asks me to please, send him/her the code, and promises that he/she will only read it, no portion will be copied (yes, we have a problem). Your friend will eventually include a portion of the code, or even worse, will upload one of your files “by mistake” (it happened).
Work in the project in an academy. The professor explains some aspects of the solution but without showing any code (no problem for us, up to you)
In the academy the project solution is illustrated with code (yes, we have a problem). We will receive several submissions almost identical, unequivocal sign of a cooperative solving strategy.

All these situations can be summarized in two fundamental guidelines. Your code can only be seen by your teammates, and you can only see your own code. And when you use a source refer to it in the documentation included in the file header. In any case, when in doubt, ask!

If a plagiarism case is detected, as it in previous occasions, the school board will be informed of the situation and a disciplinary procedure will be opened with the involved students. The course score, in such case will be zero.

UC3M

Telematic/Audiovisual Syst./Communication Syst. Engineering

Systems Architecture

September 2017 - January 2018