2020/2/29 CSCI 142: Computer Science II – Project 1 https://www.cs.rit.edu/~csci142/Projects/Overload/Overload.html#TOC2 1/7 Night Mode CSCI 142: Computer Science 2 Project 1 — Overload! Document version of 20 February 2020 1 Introduction 2 Basic Operation 3 Input/Output Specifications 3.1 Input Error-Checking and Guarantees 3.2 Output 3.3 Design Requirements 3.4 Style 4 Code Acquisition 5 Tips and Tricks 6 Submission 6.1 Grading 1 Introduction For this project we are interested in simulating the flow of electricity through the wiring in a home. You will write a set of Java classes that represents the components in such a system and observe the behavior as items are added, switched on, and switched off. First, we need to review the basic concepts that will be part of this lab. The definitions here are only as precise and as detailed as they have to be for the tasks associated with the assignment. circuit a path over which electric current flows For our purposes, imagine a hierarchical structure to the circuits of a house. At the root of each hierarchy is a power source. Every electricity-drawing device in the house draws current from a (probably solitary) power source. There will be multiple sub-circuits that are part of the main circuit. Circuit breakers are at the roots of each subtree representing each sub-circuit. Outlets are connected to the circuit breakers, into which appliances, which can be switched on and off, are attached. current the flow of electrons in a wire, measured in amperes (amps). This is the measurement unit of interest. Current is additive. This is what determines load. appliance a current-drawing device on a circuit Examples are electric stove, furnace, washing machine, lamp, toaster, television, and phone charger. Every appliance has a rated amount of current that it draws when in use, i.e., switched on. This current usage is constant the entire time the appliance is turned on. All appliances can be switched on and off, and they all should be plugged into outlets. load 2020/2/29 CSCI 142: Computer Science II – Project 1 https://www.cs.rit.edu/~csci142/Projects/Overload/Overload.html#TOC2 2/7 how much current is being drawn by a component We calculate the load on any component as the sum of the currents from all switched-on appliances, connected directly or indirectly, to the component. overload when a circuit breaker’s load is too high Every sub-circuit has a maximum allowed current, determined by the rating of its circuit breaker. If the current drawn on a circuit exceeds this level, there is risk of heat-induced electrical fire. To prevent this, the circuit breaker will automatically switch off, i.e., trip, when the current gets too high, effectively shutting down power to the sub- circuit. 2 Basic Operation We start with more definitions, this time of terms used in your software simulation. These concepts will become clearer with examples that appear later in the document. source, of a component C The component that is providing power to component C Power sources have no sources; they generate their own power. loads, of a component C The components that draw power from component C to engage a component To begin receiving power from a component’s source draw The act of pulling current from a component’s source Components draw current when at least some appliances at the leaves of the given component’s subtree are engaged and switched on. The basic functionality for this program is to be able to add components to the system, switch them on and off, keep track of the changes in current usage, and display those changes. All components except power supplies specify what their sources of power are when they are created. This cannot change during a simulation. This means that components cannot be disconnected, either. Circuit breakers and appliances, that is, components with switches, are off when they are first created. When the setup phase is complete (see the next section), the power sources at the root of the circuit trees are engaged. This causes the components, probably circuit breakers, to be engaged. The sequence stops there, because circuit breakers are initially off. Power sources remain engaged for the remainder of the simulation. When an appliance is switched on, it draws more current from its source component, which is typically an outlet. That outlet will then draw more current from its source, and so on recursively up the circuit tree. The opposite happens when an appliance is switched off. When a circuit breaker is switched on the working is a bit more complicated. Assuming the circuit breaker is engaged, all components in its load are engaged, and so on recursively down to the appliances. At this point in the simulation some appliances may be switched on, so they start drawing current. This information will make it up to the circuit breaker and beyond. When a circuit breaker is switched off, either manually or because it trips, it still messages upward (through its source) that it is no longer drawing any current. It must also disengage its loads, and so on recursively down to the appliances. At that point any switched-on appliances will stop drawing current. This information makes it back up to the circuit breaker, so one could conceivably write code that makes sure that, after switching off, that the draw at the circuit breaker does get to 0. This activity is clarified further through use of sample input files and their resulting output, and through diagrams of actual circuits. 3 Input/Output Specifications The input has two parts. 1. The first part is stored in a configuration file. It contains all the components and connections that exist before the simulation begins. The lines of this file start with a component type. There are no other component types. PowerSource CircuitBreaker 2020/2/29 CSCI 142: Computer Science II – Project 1 https://www.cs.rit.edu/~csci142/Projects/Overload/Overload.html#TOC2 3/7 Outlet Appliance After the type is the component’s unique name. For all components but PowerSource there is a third value on the line: the “parent” component to which it is connected, which we call its source. Finally Appliances and CircuitBreakers have a fourth value, an integer, used for rated draw and maximum rated load, respectively. A sample configuration file is shown below. Sample configuration file config4.txt PowerSource Home CircuitBreaker CB Home 15 Outlet O_A CB Outlet O_B CB Appliance Light1 O_A 1 Appliance Light2 O_A 1 Appliance Toaster O_B 10 The configuration file must define components in a top-down order. That is, if a component is attached to something, that something must have already been defined on an earlier line in the file. After the configuration file is read, the power supplies (there may be more than one) are engaged, but since all switches are turned off initially, no current is actually flowing. 2. Once running, your code must accept actions specified by the user from the console (standard input). To introduce a new component, use the connect command, followed by the same information you specify in a line in the configuration file. To switch a component, use the toggle command followed by the name of the previously mentioned circuit breaker or appliance. If the component was off, it switches on. If the component was on, it switches off. Use the display command to see a rendering of the circuit as a tree. Output format is shown in the examples. (This is the one case where you should be using System.out’s print methods directly.) The following input, after reading config4.txt, will cause the circuit breaker to blow when the vacuum cleaner is turned on. This gets remedied by switching off one light and then resetting the circuit breaker. Sample Action File config4_inA.txt display toggle CB toggle Light1 toggle Light2 toggle Toaster connect Appliance Vacuum O_A 4 display toggle Vacuum toggle Light1 toggle CB display toggle Vacuum quit Program Output (provided in config4_outA.txt) Overload Project, CS2 PowerSource Home(draw 0): creating CircuitBreaker CB(off; draw 0; limit 0): creating PowerSource Home(draw 0)
attaching–> CircuitBreaker CB(off; draw 0; limit 0) Outlet O_A(draw 0): creating CircuitBreaker CB(off; draw 0; limit 15) attaching–> Outlet O_A(draw 0) Outlet O_B(draw 0): creating CircuitBreaker CB(off; draw 0; limit 15) attaching–> Outlet O_B(draw 0) Appliance Light1(off; rating 0): creating Outlet O_A(draw 0) attaching–> Appliance Light1(off; rating 0) Appliance Light2(off; rating 0): creating 2020/2/29 CSCI 142: Computer Science II – Project 1 https://www.cs.rit.edu/~csci142/Projects/Overload/Overload.html#TOC2 4/7 Outlet O_A(draw 0) attaching–> Appliance Light2(off; rating 0) Appliance Toaster(off; rating 0): creating Outlet O_B(draw 0) attaching–> Appliance Toaster(off; rating 0) 7 components created. Starting up the main circuit(s). PowerSource Home(draw 0): powering up PowerSource Home(draw 0): engaging CircuitBreaker CB(off; draw 0; limit 15): engaging ? -> display[] + PowerSource Home(draw 0) + CircuitBreaker CB(off; draw 0; limit 15) + Outlet O_A(draw 0) + Appliance Light1(off; rating 1) + Appliance Light2(off; rating 1) + Outlet O_B(draw 0) + Appliance Toaster(off; rating 10) ? -> toggle[CB] CircuitBreaker CB(on; draw 0; limit 15): switching on Outlet O_A(draw 0): engaging Appliance Light1(off; rating 1): engaging Appliance Light2(off; rating 1): engaging Outlet O_B(draw 0): engaging Appliance Toaster(off; rating 10): engaging ? -> toggle[Light1] Appliance Light1(on; rating 1): switching on Outlet O_A(draw 1): draw change 1 CircuitBreaker CB(on; draw 1; limit 15): draw change 1 PowerSource Home(draw 1): draw change 1 ? -> toggle[Light2] Appliance Light2(on; rating 1): switching on Outlet O_A(draw 2): draw change 1 CircuitBreaker CB(on; draw 2; limit 15): draw change 1 PowerSource Home(draw 2): draw change 1 ? -> toggle[Toaster] Appliance Toaster(on; rating 10): switching on Outlet O_B(draw 10): draw change 10 CircuitBreaker CB(on; draw 12; limit 15): draw change 10 PowerSource Home(draw 12): draw change 10 ? -> connect[Appliance, Vacuum, O_A, 4] Appliance Vacuum(off; rating 0): creating Outlet O_A(draw 2) attaching–> Appliance Vacuum(off; rating 0) Appliance Vacuum(off; rating 0): engaging ? -> display[] + PowerSource Home(draw 12) + CircuitBreaker CB(on; draw 12; limit 15) + Outlet O_A(draw 2) + Appliance Light1(on; rating 1) + Appliance Light2(on; rating 1) + Appliance Vacuum(off; rating 4) + Outlet O_B(draw 10) + Appliance Toaster(on; rating 10) ? -> toggle[Vacuum] Appliance Vacuum(on; rating 4): switching on Outlet O_A(draw 6): draw change 4 CircuitBreaker CB(on; draw 16; limit 15): has blown; current would be 16 CircuitBreaker CB(off; draw 16; limit 15): switching off PowerSource Home(draw 0): draw change -12 Outlet O_A(draw 6): disengaging Appliance Light1(on; rating 1): disengaging Appliance Light1(on; rating 1): draw change -1 Outlet O_A(draw 5): draw change -1 Appliance Light2(on; rating 1): disengaging Appliance Light2(on; rating 1): draw change -1 Outlet O_A(draw 4): draw change -1 Appliance Vacuum(on; rating 4): disengaging Appliance Vacuum(on; rating 4): draw change -4 2020/2/29 CSCI 142: Computer Science II – Project 1 https://www.cs.rit.edu/~csci142/Projects/Overload/Overload.html#TOC2 5/7 Outlet O_A(draw 0): draw change -4 Outlet O_B(draw 10): disengaging Appliance Toaster(on; rating 10): disengaging Appliance Toaster(on; rating 10): draw change -10 Outlet O_B(draw 0): draw change -10 ? -> toggle[Light1] Appliance Light1(off; rating 1): switching off ? -> toggle[CB] CircuitBreaker CB(on; draw 0; limit 15): switching on Outlet O_A(draw 0): engaging Appliance Light1(off; rating 1): engaging Appliance Light2(on; rating 1): engaging Appliance Light2(on; rating 1): draw change 1 Outlet O_A(draw 1): draw change 1 CircuitBreaker CB(on; draw 1; limit 15): draw change 1 PowerSource Home(draw 1): draw change 1 Appliance Vacuum(on; rating 4): engaging Appliance Vacuum(on; rating 4): draw change 4 Outlet O_A(draw 5): draw change 4 CircuitBreaker CB(on; draw 5; limit 15): draw change 4 PowerSource Home(draw 5): draw change 4 Outlet O_B(draw 0): engaging Appliance Toaster(on; rating 10): engaging Appliance Toaster(on; rating 10): draw change 10 Outlet O_B(draw 10): draw change 10 CircuitBreaker CB(on; draw 15; limit 15): draw change 10 PowerSource Home(draw 15): draw change 10 ? -> display[] + PowerSource Home(draw 15) + CircuitBreaker CB(on; draw 15; limit 15) + Outlet O_A(draw 5) + Appliance Light1(off; rating 1) + Appliance Light2(on; rating 1) + Appliance Vacuum(on; rating 4) + Outlet O_B(draw 10) + Appliance Toaster(on; rating 10) ? -> toggle[Vacuum] Appliance Vacuum(off; rating 4): switching off Outlet O_A(draw 1): draw change -4 CircuitBreaker CB(on; draw 11; limit 15): draw change -4 PowerSource Home(draw 11): draw change -4 ? -> quit[] Diagrams showing a dynamic view of parts of the above example can be found in object-diagrams.pdf. 3.1 Input Error-Checking and Guarantees We make the following guarantees for any input that your program is tested with. All values related to current will be integer values. Although the expected chain of connections is expected to be from PowerSource to CircuitBreaker to Outlet to Appliance, you do not have to error check for this. You are, however, expected to handle some error cases. You can easily see what errors you must handle by looking at the starter contents of the class Overload. Specifically, you must handle the following. Request to add a component with a name that is already in use by another component in the system. (There can be only one component with any given name in the system.) Request to add a component but the specified source name is not in use by any existing component. Request to toggle an unswitched component. Note that although technically there is a restriction on what the source of each component may be, this will not be considered an error. This will allow us to make tests as simple as connecting an Appliance to a PowerSource. Do not flag such things as errors. 2020/2/29 CSCI 142: Computer Science II – Project 1 https://www.cs.rit.edu/~csci142/Projects/Overload/Overload.html#TOC2 6/7 3.2 Output Except for the implementation of the display command, the code you write will not contain any direct print statements. Use the static methods in the Reporter class that comes in the starter code, explained below. 3.3 Design Requirements Your main program will be in a class named Overload. Your design will be judged with an eye towards cohesiveness of purpose within each method and each class, good separation of concerns among the classes, minimal duplication of functionality, including appropriate use of inheritance. 3.4 Style All code should be written commented according to the course style guidelines. 4 Code Acquisition Your instructor will give you a GitHub classroom URL to go to to acquire a clone of the starter code. A small amount of starter code for Overload.java is provided. The main reason is to give you the output error message strings. Reporter.java program is provided for you to do output so that the messages can be standardized. The Tests.java program is provided for you to see if your code is working properly. It is not part of the final submission. See the Tips section below. A small amount of starter code for Overload.java is provided. 5 Tips and Tricks Here are some details to keep in mind as you design and code. Some of these are rules for the electrical simulation that you need to follow. Others are implementation suggestions. More tips specifically about coding can be found in the auxiliary document tips-and-tricks.html. Documentation for a suggested implementation of the Component abstract class is available here. You do not have to follow it, but even if you don’t, it may give you some design ideas. As you can see in the grading section, you will be evaluated on your design. Do not do any console output in t
he code you write. Use the Reporter class and the starting code in Overload. Although we don’t provide a complete design in UML or via javadocs, you can infer the proper signatures to your individual Component classes by making use of the Tests.java test program. That program will not compile until you write your constructors properly. You provide a number as a command line argument to run a specific test. You provide no arguments to run all tests. The allowed structure for the electrical system for this lab requires a PowerSource at each circuit tree’s root. CircuitBreakers connect to PowerSources, Outlets connect to CircuitBreakers, and Appliances connect to Outlets. This is not error checked. There are no limits as to how many loads can be connected to a Component, except for an Appliance, which takes none. When something turns on, everything below it in the wiring tree gets invoked with engage() method calls. Engaged is our way of saying that power is getting to a given Component. The exception to this is a component with a switch — in our case a CircuitBreaker or an Appliance. engage() calls don’t get past an open switch. We are treating an overload event as disengaging all appliances on the sub-circuit. This effectively turns off all appliances on the affected circuit. But remember that the appliances are still switched on. This is important for when the circuit is restored. When something that is engaged turns on, everything above it in the wiring tree will get invoked with draw(int) method calls. This is used to adjust how much current (draw) a Component is demanding from its source. The same thing happens when an engaged component is switched off, except that the argument to draw will be negative. Remember that when an overload occurs, this type of switching off necessitates sending messages in two directions. One set of messages is sent down the tree to disengage all children of the switched-off sub-circuit. Then, messages are sent back up from the affected appliances to indicate that they are no longer drawing any current. Let’s look at the details. But the best way to understand this process is to look at the diagrams and the output from the examples. Also keep in mind that in a real electrical circuit everything happens in parallel. Therefore the order we have chosen for the reference solution is somewhat arbitrary. 2020/2/29 CSCI 142: Computer Science II – Project 1 https://www.cs.rit.edu/~csci142/Projects/Overload/Overload.html#TOC2 7/7 When an appliance is toggled on, the current adjustments (draw) are made progressively up the chain in the system. If too much draw is placed on a CircuitBreaker, the breaker trips, or switches off. Then a series of events occurs 1. The circuit breaker still registers as having the large draw being demanded of it. This is because it is consistent with the draw from all its loads. 2. The CircuitBreaker is switched off. (Hint: this is behavior in common with an Appliance.) 3. A changeDraw(int) method call is use to inform the breaker’s source (a PowerSource) that it is no longer drawing any current. 4. disengage() calls are made to all the loads under that breaker. 5. This in turn causes Appliances to disengage. They will send changeDraw(int) messages up the tree back to the breaker. 6. The breaker dutifully lowers its draw each time such a call occurs. When the last changeDraw(int) call is done, the CircuitBreaker will have a draw of 0. Note that a changeDraw(int) call in this case does not get past the breaker to its source. That already happened in an earlier step. Use protected fields and methods where appropriate. Protected members are available to derived classes, but not meant to be available to the whole world. Ideally, your Overload class does not need, and should not have access to these protected fields and methods. However, the protected keyword also gives access to all classes in the same package. By doing all development in same package, your simulator class will actually have access to these protected fields and methods. This is a shortcoming of Java (in some people’s opinions), so don’t worry about it. 6 Submission Your main program file should be named Overload.java. You should zip all of your Java source files, i.e., the content of your src directory, into project1.zip and submit it to the Project 1 Assignment dropbox in MyCourses by the due date. 6.1 Grading The grade breakdown for this lab is as follows. Functionality: 80% Design: 20% Code Style & Version Control: up to 10% off
