From 8691d75d7785bd0b084a4be8f0a7457d0744d7b5 Mon Sep 17 00:00:00 2001 From: Vegard Engen Date: Tue, 13 Jun 2017 10:11:22 +0100 Subject: [PATCH] Release 1.0 of hmn-core --- .gitignore | 1 + IPR.md | 27 + README.md | 55 ++ licenses/LGPL_v2.1.txt | 502 ++++++++++++++++++ licenses/MIT_(Newtonsoft).txt | 18 + pom.xml | 124 +++++ .../ac/soton/itinnovation/hmncore/Agent.java | 52 ++ .../soton/itinnovation/hmncore/Artefact.java | 114 ++++ .../itinnovation/hmncore/Connection.java | 228 ++++++++ .../itinnovation/hmncore/ConnectionType.java | 79 +++ .../itinnovation/hmncore/CultureType.java | 80 +++ .../ac/soton/itinnovation/hmncore/Edge.java | 317 +++++++++++ .../soton/itinnovation/hmncore/EdgeStats.java | 102 ++++ .../itinnovation/hmncore/GenderType.java | 84 +++ .../uk/ac/soton/itinnovation/hmncore/HMN.java | 345 ++++++++++++ .../ac/soton/itinnovation/hmncore/Human.java | 206 +++++++ .../soton/itinnovation/hmncore/Machine.java | 164 ++++++ .../ac/soton/itinnovation/hmncore/Node.java | 368 +++++++++++++ .../hmncore/SexualOrientationType.java | 84 +++ src/main/resources/logback-hmncore.xml | 16 + uml/hmn-core-uml.vsdx | Bin 0 -> 121129 bytes 21 files changed, 2966 insertions(+) create mode 100644 .gitignore create mode 100644 IPR.md create mode 100644 README.md create mode 100644 licenses/LGPL_v2.1.txt create mode 100644 licenses/MIT_(Newtonsoft).txt create mode 100644 pom.xml create mode 100644 src/main/java/uk/ac/soton/itinnovation/hmncore/Agent.java create mode 100644 src/main/java/uk/ac/soton/itinnovation/hmncore/Artefact.java create mode 100644 src/main/java/uk/ac/soton/itinnovation/hmncore/Connection.java create mode 100644 src/main/java/uk/ac/soton/itinnovation/hmncore/ConnectionType.java create mode 100644 src/main/java/uk/ac/soton/itinnovation/hmncore/CultureType.java create mode 100644 src/main/java/uk/ac/soton/itinnovation/hmncore/Edge.java create mode 100644 src/main/java/uk/ac/soton/itinnovation/hmncore/EdgeStats.java create mode 100644 src/main/java/uk/ac/soton/itinnovation/hmncore/GenderType.java create mode 100644 src/main/java/uk/ac/soton/itinnovation/hmncore/HMN.java create mode 100644 src/main/java/uk/ac/soton/itinnovation/hmncore/Human.java create mode 100644 src/main/java/uk/ac/soton/itinnovation/hmncore/Machine.java create mode 100644 src/main/java/uk/ac/soton/itinnovation/hmncore/Node.java create mode 100644 src/main/java/uk/ac/soton/itinnovation/hmncore/SexualOrientationType.java create mode 100644 src/main/resources/logback-hmncore.xml create mode 100644 uml/hmn-core-uml.vsdx diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b83d222 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +/target/ diff --git a/IPR.md b/IPR.md new file mode 100644 index 0000000..2dc583c --- /dev/null +++ b/IPR.md @@ -0,0 +1,27 @@ +# Intellectual Property Rights (IPR) Specification + +## IPR for the hmn-core software + +This software distribution is licensed under the terms found in the file: + +``licences/LGPL_v2.1.txt`` + +The IT Innovation software is the source code and the following associated jars + + hmn-core-.jar + hmn-core--sources.jar + + +# IPR for third party libraries + +The hmn-core software requires various third-party libraries to compile +and/or execute. These libraries and their associated licences are detailed +below. + +## LGPL + + ch.qos.logback:logback-classic:1.1.1 + +## MIT Licence + + org.slf4j:slf4j-api:1.6.1 diff --git a/README.md b/README.md new file mode 100644 index 0000000..16d9cc3 --- /dev/null +++ b/README.md @@ -0,0 +1,55 @@ +# HUMANE Core HMN Model (hmn-core) + +This project provides a Java implementation of the Core HMN Model developed in the +HUMANE project by the University of Southampton IT Innovation Centre http://www.it-innovation.soton.ac.uk/. + +The Core HMN Model was developed to support the modelling and simulation of +Human-Machine Networks. This model reflects key aspects of HMNs captured in the +HUMANE typology to describe the actors, their interactions and structure of the network. + +Further details about the HUMANE project, typology and simulation +modelling work can be found on: https://humane2020.eu. + +# Copyright + +The source code in this distribution is (c) Copyright University of Southampton +IT Innovation Centre, 2017. + +# Licences + +The source code for hmn-core is provided under the LGPL v2.1; the licence +agreement for this can be found in the LICENSE file and folder named 'licences'. + +A complete list of licences for this software and associated third party +software can be found in the IPR.md file. + +# Software Dependencies + +The following 3rd party software is required: + +* Java 1.8 +* Maven 3.x + +## Setting up Java and Maven + +Please refer to the respective software provider's instructions: + +* Java JDK: http://www.oracle.com/technetwork/java/javase/downloads/index.html +* Maven: http://maven.apache.org/download.cgi + +# Building the hmn-core software + +This software requires maven 3.x to build, which you can do with the follow command: + +``` + mvn install +``` + +To generate JavaDoc, the package profile must be used when compiling the code: + +``` + mvn install -P package +``` + +The JavaDoc will be created in ./target/javadoc + diff --git a/licenses/LGPL_v2.1.txt b/licenses/LGPL_v2.1.txt new file mode 100644 index 0000000..f166cc5 --- /dev/null +++ b/licenses/LGPL_v2.1.txt @@ -0,0 +1,502 @@ + GNU LESSER GENERAL PUBLIC LICENSE + Version 2.1, February 1999 + + Copyright (C) 1991, 1999 Free Software Foundation, Inc. + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + +[This is the first released version of the Lesser GPL. It also counts + as the successor of the GNU Library Public License, version 2, hence + the version number 2.1.] + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +Licenses are intended to guarantee your freedom to share and change +free software--to make sure the software is free for all its users. + + This license, the Lesser General Public License, applies to some +specially designated software packages--typically libraries--of the +Free Software Foundation and other authors who decide to use it. You +can use it too, but we suggest you first think carefully about whether +this license or the ordinary General Public License is the better +strategy to use in any particular case, based on the explanations below. + + When we speak of free software, we are referring to freedom of use, +not price. Our General Public Licenses are designed to make sure that +you have the freedom to distribute copies of free software (and charge +for this service if you wish); that you receive source code or can get +it if you want it; that you can change the software and use pieces of +it in new free programs; and that you are informed that you can do +these things. + + To protect your rights, we need to make restrictions that forbid +distributors to deny you these rights or to ask you to surrender these +rights. These restrictions translate to certain responsibilities for +you if you distribute copies of the library or if you modify it. + + For example, if you distribute copies of the library, whether gratis +or for a fee, you must give the recipients all the rights that we gave +you. You must make sure that they, too, receive or can get the source +code. If you link other code with the library, you must provide +complete object files to the recipients, so that they can relink them +with the library after making changes to the library and recompiling +it. And you must show them these terms so they know their rights. + + We protect your rights with a two-step method: (1) we copyright the +library, and (2) we offer you this license, which gives you legal +permission to copy, distribute and/or modify the library. + + To protect each distributor, we want to make it very clear that +there is no warranty for the free library. Also, if the library is +modified by someone else and passed on, the recipients should know +that what they have is not the original version, so that the original +author's reputation will not be affected by problems that might be +introduced by others. + + Finally, software patents pose a constant threat to the existence of +any free program. We wish to make sure that a company cannot +effectively restrict the users of a free program by obtaining a +restrictive license from a patent holder. Therefore, we insist that +any patent license obtained for a version of the library must be +consistent with the full freedom of use specified in this license. + + Most GNU software, including some libraries, is covered by the +ordinary GNU General Public License. This license, the GNU Lesser +General Public License, applies to certain designated libraries, and +is quite different from the ordinary General Public License. We use +this license for certain libraries in order to permit linking those +libraries into non-free programs. + + When a program is linked with a library, whether statically or using +a shared library, the combination of the two is legally speaking a +combined work, a derivative of the original library. The ordinary +General Public License therefore permits such linking only if the +entire combination fits its criteria of freedom. The Lesser General +Public License permits more lax criteria for linking other code with +the library. + + We call this license the "Lesser" General Public License because it +does Less to protect the user's freedom than the ordinary General +Public License. It also provides other free software developers Less +of an advantage over competing non-free programs. These disadvantages +are the reason we use the ordinary General Public License for many +libraries. However, the Lesser license provides advantages in certain +special circumstances. + + For example, on rare occasions, there may be a special need to +encourage the widest possible use of a certain library, so that it becomes +a de-facto standard. To achieve this, non-free programs must be +allowed to use the library. A more frequent case is that a free +library does the same job as widely used non-free libraries. In this +case, there is little to gain by limiting the free library to free +software only, so we use the Lesser General Public License. + + In other cases, permission to use a particular library in non-free +programs enables a greater number of people to use a large body of +free software. For example, permission to use the GNU C Library in +non-free programs enables many more people to use the whole GNU +operating system, as well as its variant, the GNU/Linux operating +system. + + Although the Lesser General Public License is Less protective of the +users' freedom, it does ensure that the user of a program that is +linked with the Library has the freedom and the wherewithal to run +that program using a modified version of the Library. + + The precise terms and conditions for copying, distribution and +modification follow. Pay close attention to the difference between a +"work based on the library" and a "work that uses the library". The +former contains code derived from the library, whereas the latter must +be combined with the library in order to run. + + GNU LESSER GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License Agreement applies to any software library or other +program which contains a notice placed by the copyright holder or +other authorized party saying it may be distributed under the terms of +this Lesser General Public License (also called "this License"). +Each licensee is addressed as "you". + + A "library" means a collection of software functions and/or data +prepared so as to be conveniently linked with application programs +(which use some of those functions and data) to form executables. + + The "Library", below, refers to any such software library or work +which has been distributed under these terms. A "work based on the +Library" means either the Library or any derivative work under +copyright law: that is to say, a work containing the Library or a +portion of it, either verbatim or with modifications and/or translated +straightforwardly into another language. (Hereinafter, translation is +included without limitation in the term "modification".) + + "Source code" for a work means the preferred form of the work for +making modifications to it. For a library, complete source code means +all the source code for all modules it contains, plus any associated +interface definition files, plus the scripts used to control compilation +and installation of the library. + + Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running a program using the Library is not restricted, and output from +such a program is covered only if its contents constitute a work based +on the Library (independent of the use of the Library in a tool for +writing it). Whether that is true depends on what the Library does +and what the program that uses the Library does. + + 1. You may copy and distribute verbatim copies of the Library's +complete source code as you receive it, in any medium, provided that +you conspicuously and appropriately publish on each copy an +appropriate copyright notice and disclaimer of warranty; keep intact +all the notices that refer to this License and to the absence of any +warranty; and distribute a copy of this License along with the +Library. + + You may charge a fee for the physical act of transferring a copy, +and you may at your option offer warranty protection in exchange for a +fee. + + 2. You may modify your copy or copies of the Library or any portion +of it, thus forming a work based on the Library, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) The modified work must itself be a software library. + + b) You must cause the files modified to carry prominent notices + stating that you changed the files and the date of any change. + + c) You must cause the whole of the work to be licensed at no + charge to all third parties under the terms of this License. + + d) If a facility in the modified Library refers to a function or a + table of data to be supplied by an application program that uses + the facility, other than as an argument passed when the facility + is invoked, then you must make a good faith effort to ensure that, + in the event an application does not supply such function or + table, the facility still operates, and performs whatever part of + its purpose remains meaningful. + + (For example, a function in a library to compute square roots has + a purpose that is entirely well-defined independent of the + application. Therefore, Subsection 2d requires that any + application-supplied function or table used by this function must + be optional: if the application does not supply it, the square + root function must still compute square roots.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Library, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Library, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote +it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Library. + +In addition, mere aggregation of another work not based on the Library +with the Library (or with a work based on the Library) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may opt to apply the terms of the ordinary GNU General Public +License instead of this License to a given copy of the Library. To do +this, you must alter all the notices that refer to this License, so +that they refer to the ordinary GNU General Public License, version 2, +instead of to this License. (If a newer version than version 2 of the +ordinary GNU General Public License has appeared, then you can specify +that version instead if you wish.) Do not make any other change in +these notices. + + Once this change is made in a given copy, it is irreversible for +that copy, so the ordinary GNU General Public License applies to all +subsequent copies and derivative works made from that copy. + + This option is useful when you wish to copy part of the code of +the Library into a program that is not a library. + + 4. You may copy and distribute the Library (or a portion or +derivative of it, under Section 2) in object code or executable form +under the terms of Sections 1 and 2 above provided that you accompany +it with the complete corresponding machine-readable source code, which +must be distributed under the terms of Sections 1 and 2 above on a +medium customarily used for software interchange. + + If distribution of object code is made by offering access to copy +from a designated place, then offering equivalent access to copy the +source code from the same place satisfies the requirement to +distribute the source code, even though third parties are not +compelled to copy the source along with the object code. + + 5. A program that contains no derivative of any portion of the +Library, but is designed to work with the Library by being compiled or +linked with it, is called a "work that uses the Library". Such a +work, in isolation, is not a derivative work of the Library, and +therefore falls outside the scope of this License. + + However, linking a "work that uses the Library" with the Library +creates an executable that is a derivative of the Library (because it +contains portions of the Library), rather than a "work that uses the +library". The executable is therefore covered by this License. +Section 6 states terms for distribution of such executables. + + When a "work that uses the Library" uses material from a header file +that is part of the Library, the object code for the work may be a +derivative work of the Library even though the source code is not. +Whether this is true is especially significant if the work can be +linked without the Library, or if the work is itself a library. The +threshold for this to be true is not precisely defined by law. + + If such an object file uses only numerical parameters, data +structure layouts and accessors, and small macros and small inline +functions (ten lines or less in length), then the use of the object +file is unrestricted, regardless of whether it is legally a derivative +work. (Executables containing this object code plus portions of the +Library will still fall under Section 6.) + + Otherwise, if the work is a derivative of the Library, you may +distribute the object code for the work under the terms of Section 6. +Any executables containing that work also fall under Section 6, +whether or not they are linked directly with the Library itself. + + 6. As an exception to the Sections above, you may also combine or +link a "work that uses the Library" with the Library to produce a +work containing portions of the Library, and distribute that work +under terms of your choice, provided that the terms permit +modification of the work for the customer's own use and reverse +engineering for debugging such modifications. + + You must give prominent notice with each copy of the work that the +Library is used in it and that the Library and its use are covered by +this License. You must supply a copy of this License. If the work +during execution displays copyright notices, you must include the +copyright notice for the Library among them, as well as a reference +directing the user to the copy of this License. Also, you must do one +of these things: + + a) Accompany the work with the complete corresponding + machine-readable source code for the Library including whatever + changes were used in the work (which must be distributed under + Sections 1 and 2 above); and, if the work is an executable linked + with the Library, with the complete machine-readable "work that + uses the Library", as object code and/or source code, so that the + user can modify the Library and then relink to produce a modified + executable containing the modified Library. (It is understood + that the user who changes the contents of definitions files in the + Library will not necessarily be able to recompile the application + to use the modified definitions.) + + b) Use a suitable shared library mechanism for linking with the + Library. A suitable mechanism is one that (1) uses at run time a + copy of the library already present on the user's computer system, + rather than copying library functions into the executable, and (2) + will operate properly with a modified version of the library, if + the user installs one, as long as the modified version is + interface-compatible with the version that the work was made with. + + c) Accompany the work with a written offer, valid for at + least three years, to give the same user the materials + specified in Subsection 6a, above, for a charge no more + than the cost of performing this distribution. + + d) If distribution of the work is made by offering access to copy + from a designated place, offer equivalent access to copy the above + specified materials from the same place. + + e) Verify that the user has already received a copy of these + materials or that you have already sent this user a copy. + + For an executable, the required form of the "work that uses the +Library" must include any data and utility programs needed for +reproducing the executable from it. However, as a special exception, +the materials to be distributed need not include anything that is +normally distributed (in either source or binary form) with the major +components (compiler, kernel, and so on) of the operating system on +which the executable runs, unless that component itself accompanies +the executable. + + It may happen that this requirement contradicts the license +restrictions of other proprietary libraries that do not normally +accompany the operating system. Such a contradiction means you cannot +use both them and the Library together in an executable that you +distribute. + + 7. You may place library facilities that are a work based on the +Library side-by-side in a single library together with other library +facilities not covered by this License, and distribute such a combined +library, provided that the separate distribution of the work based on +the Library and of the other library facilities is otherwise +permitted, and provided that you do these two things: + + a) Accompany the combined library with a copy of the same work + based on the Library, uncombined with any other library + facilities. This must be distributed under the terms of the + Sections above. + + b) Give prominent notice with the combined library of the fact + that part of it is a work based on the Library, and explaining + where to find the accompanying uncombined form of the same work. + + 8. You may not copy, modify, sublicense, link with, or distribute +the Library except as expressly provided under this License. Any +attempt otherwise to copy, modify, sublicense, link with, or +distribute the Library is void, and will automatically terminate your +rights under this License. However, parties who have received copies, +or rights, from you under this License will not have their licenses +terminated so long as such parties remain in full compliance. + + 9. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Library or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Library (or any work based on the +Library), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Library or works based on it. + + 10. Each time you redistribute the Library (or any work based on the +Library), the recipient automatically receives a license from the +original licensor to copy, distribute, link with or modify the Library +subject to these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties with +this License. + + 11. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Library at all. For example, if a patent +license would not permit royalty-free redistribution of the Library by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Library. + +If any portion of this section is held invalid or unenforceable under any +particular circumstance, the balance of the section is intended to apply, +and the section as a whole is intended to apply in other circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 12. If the distribution and/or use of the Library is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Library under this License may add +an explicit geographical distribution limitation excluding those countries, +so that distribution is permitted only in or among countries not thus +excluded. In such case, this License incorporates the limitation as if +written in the body of this License. + + 13. The Free Software Foundation may publish revised and/or new +versions of the Lesser General Public License from time to time. +Such new versions will be similar in spirit to the present version, +but may differ in detail to address new problems or concerns. + +Each version is given a distinguishing version number. If the Library +specifies a version number of this License which applies to it and +"any later version", you have the option of following the terms and +conditions either of that version or of any later version published by +the Free Software Foundation. If the Library does not specify a +license version number, you may choose any version ever published by +the Free Software Foundation. + + 14. If you wish to incorporate parts of the Library into other free +programs whose distribution conditions are incompatible with these, +write to the author to ask for permission. For software which is +copyrighted by the Free Software Foundation, write to the Free +Software Foundation; we sometimes make exceptions for this. Our +decision will be guided by the two goals of preserving the free status +of all derivatives of our free software and of promoting the sharing +and reuse of software generally. + + NO WARRANTY + + 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO +WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. +EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR +OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY +KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE +LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME +THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN +WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY +AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU +FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR +CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE +LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING +RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A +FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF +SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH +DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Libraries + + If you develop a new library, and you want it to be of the greatest +possible use to the public, we recommend making it free software that +everyone can redistribute and change. You can do so by permitting +redistribution under these terms (or, alternatively, under the terms of the +ordinary General Public License). + + To apply these terms, attach the following notices to the library. It is +safest to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least the +"copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +Also add information on how to contact you by electronic and paper mail. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the library, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the + library `Frob' (a library for tweaking knobs) written by James Random Hacker. + + , 1 April 1990 + Ty Coon, President of Vice + +That's all there is to it! \ No newline at end of file diff --git a/licenses/MIT_(Newtonsoft).txt b/licenses/MIT_(Newtonsoft).txt new file mode 100644 index 0000000..0c2edce --- /dev/null +++ b/licenses/MIT_(Newtonsoft).txt @@ -0,0 +1,18 @@ +Copyright (c) 2007 James Newton-King + +Permission is hereby granted, free of charge, to any person obtaining a copy of this +software and associated documentation files (the "Software"), to deal in the Software +without restriction, including without limitation the rights to use, copy, modify, +merge, publish, distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice shall be included in all copies +or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, +INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF +CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE +OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. \ No newline at end of file diff --git a/pom.xml b/pom.xml new file mode 100644 index 0000000..14d2f8a --- /dev/null +++ b/pom.xml @@ -0,0 +1,124 @@ + + 4.0.0 + uk.ac.soton.itinnovation.hmncore + hmn-core + 1.0 + jar + + + UTF-8 + 1.8 + 3.6.1 + 3.0.2 + 3.0.1 + 4.12 + 1.2.1 + 2.10.4 + target/javadoc + + + + + + + + org.apache.maven.plugins + maven-compiler-plugin + ${hmncore.maven.compiler} + + ${hmncore.java.version} + ${hmncore.java.version} + + + + + + org.apache.maven.plugins + maven-resources-plugin + ${hmncore.maven.resource} + + ${project.build.sourceEncoding} + + + + + + org.apache.maven.plugins + maven-source-plugin + ${hmncore.maven.source} + + + attach-sources + compile + + jar-no-fork + + + + + + + + + + + + package + + + + + + org.apache.maven.plugins + maven-javadoc-plugin + ${hmncore.javadocplugin.version} + + + attach-javadocs + package + + aggregate + + + + ${hmncore.javadocpath} + . + + + + + + + + + + + + + + + junit + junit + ${hmncore.junit.version} + test + + + + + ch.qos.logback + logback-classic + ${hmncore.logback.version} + + + + + + + LGPL 2.1 + http://www.gnu.org/licenses/lgpl-2.1.htm + + + + + diff --git a/src/main/java/uk/ac/soton/itinnovation/hmncore/Agent.java b/src/main/java/uk/ac/soton/itinnovation/hmncore/Agent.java new file mode 100644 index 0000000..07f61e2 --- /dev/null +++ b/src/main/java/uk/ac/soton/itinnovation/hmncore/Agent.java @@ -0,0 +1,52 @@ +///////////////////////////////////////////////////////////////////////// +// +// © University of Southampton IT Innovation Centre, 2017 +// +// Copyright in this software belongs to University of Southampton +// IT Innovation Centre of Gamma House, Enterprise Road, +// Chilworth Science Park, Southampton, SO16 7NS, UK. +// +// This software may not be used, sold, licensed, transferred, copied +// or reproduced in whole or in part in any manner or form or in or +// on any media by any person other than in accordance with the terms +// of the Licence Agreement supplied with the software, or otherwise +// without the prior written consent of the copyright owners. +// +// This software is distributed WITHOUT ANY WARRANTY, without even the +// implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +// PURPOSE, except where stated in the Licence Agreement supplied with +// the software. +// +// Created By : Vegard Engen +// Created Date : 2017-02-02 +// Created for Project : HUMANE +// +///////////////////////////////////////////////////////////////////////// +package uk.ac.soton.itinnovation.hmncore; + +import java.io.Serializable; + +/** + * An abstract class representing an Agent in the HMN. At the core level, this can + * be either a Human or a Machine. + * @see Human + * @see Machine + * @author Vegard Engen + */ +public abstract class Agent extends Node implements Serializable +{ + /** + * Default constructor. + */ + public Agent() + { + + } + + /** + * Abstract method that should be implemented by actors in a simulated + * environment for a HMN, which should be invoked during the course of a simulation. + * @throws Exception For any errors. + */ + public abstract void takeAction() throws Exception; +} diff --git a/src/main/java/uk/ac/soton/itinnovation/hmncore/Artefact.java b/src/main/java/uk/ac/soton/itinnovation/hmncore/Artefact.java new file mode 100644 index 0000000..68d9975 --- /dev/null +++ b/src/main/java/uk/ac/soton/itinnovation/hmncore/Artefact.java @@ -0,0 +1,114 @@ +///////////////////////////////////////////////////////////////////////// +// +// © University of Southampton IT Innovation Centre, 2017 +// +// Copyright in this software belongs to University of Southampton +// IT Innovation Centre of Gamma House, Enterprise Road, +// Chilworth Science Park, Southampton, SO16 7NS, UK. +// +// This software may not be used, sold, licensed, transferred, copied +// or reproduced in whole or in part in any manner or form or in or +// on any media by any person other than in accordance with the terms +// of the Licence Agreement supplied with the software, or otherwise +// without the prior written consent of the copyright owners. +// +// This software is distributed WITHOUT ANY WARRANTY, without even the +// implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +// PURPOSE, except where stated in the Licence Agreement supplied with +// the software. +// +// Created By : Vegard Engen +// Created Date : 2017-02-02 +// Created for Project : HUMANE +// +///////////////////////////////////////////////////////////////////////// +package uk.ac.soton.itinnovation.hmncore; + +import java.io.Serializable; +import java.util.Date; + +/** + * An abstract class reflecting an Artefact in the HMN, which is a type of node that + * does not have agency. That could be a file, a forum post, a Tweet, an email, etc. + * @author Vegard Engen + */ +public class Artefact extends Node implements Serializable +{ + // private String artefactID; // use nodeID + protected Agent creator; + protected Date creationDate; + + /** + * Default constructor, which does nothing. + */ + public Artefact() { } + + /** + * Constructor to set the node who created this artefact and the date this occurred. + * @param id The ID of the artefact. + */ + public Artefact(String id) + { + this.nodeID = id; + } + + /** + * Constructor to set the node who created this artefact and the date this occurred. + * @param a Agent object for the creator of this artefact. + * @param d The date for which the artefact was created. + */ + public Artefact(Agent a, Date d) + { + this.creator = a; + this.creationDate = d; + } + + /** + * Constructor to set the node who created this artefact and the date this occurred. + * @param id The ID of the artefact. + * @param a Agent object for the creator of this artefact. + * @param d The date for which the artefact was created. + */ + public Artefact(String id, Agent a, Date d) + { + this.nodeID = id; + this.creator = a; + this.creationDate = d; + } + + /** + * Get the creator (agent) of this artefact. + * @return Agent object. + */ + public Agent getCreator() + { + return creator; + } + + /** + * Set the creator (agent) of this artefact. + * @param creator Agent object. + */ + public void setCreator(Agent creator) + { + this.creator = creator; + } + + /** + * Get the date for which this artefact was created. + * @return Date object. + */ + public Date getCreationDate() + { + return creationDate; + } + + /** + * Set the date this artefact was created. + * @param creationDate Date object. + */ + public void setCreationDate(Date creationDate) + { + this.creationDate = creationDate; + } +} diff --git a/src/main/java/uk/ac/soton/itinnovation/hmncore/Connection.java b/src/main/java/uk/ac/soton/itinnovation/hmncore/Connection.java new file mode 100644 index 0000000..8fa6136 --- /dev/null +++ b/src/main/java/uk/ac/soton/itinnovation/hmncore/Connection.java @@ -0,0 +1,228 @@ +///////////////////////////////////////////////////////////////////////// +// +// © University of Southampton IT Innovation Centre, 2017 +// +// Copyright in this software belongs to University of Southampton +// IT Innovation Centre of Gamma House, Enterprise Road, +// Chilworth Science Park, Southampton, SO16 7NS, UK. +// +// This software may not be used, sold, licensed, transferred, copied +// or reproduced in whole or in part in any manner or form or in or +// on any media by any person other than in accordance with the terms +// of the Licence Agreement supplied with the software, or otherwise +// without the prior written consent of the copyright owners. +// +// This software is distributed WITHOUT ANY WARRANTY, without even the +// implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +// PURPOSE, except where stated in the Licence Agreement supplied with +// the software. +// +// Created By : Vegard Engen +// Created Date : 2017-02-02 +// Created for Project : HUMANE +// +///////////////////////////////////////////////////////////////////////// +package uk.ac.soton.itinnovation.hmncore; + +import java.io.Serializable; +import java.util.HashMap; +import java.util.Map; + +/** + * A class representing a connection that an Agent (Human or Machine) has to an Edge + * between the two. Edges are directional, and a Connection from the source Agent to the + * destination/sink Agent encapsulates properties determining how they may interact with + * the destination/sink on the basis of properties like trust. + * + * Similarly, Connection objects associated with the destination Agent encapsulates + * properties determining how they may behave with regards to the interactions they receive. + * + * This class includes trust and trustworthiness as explicit properties. Their use + * warrants explanation, as the use of these properties depends on whether the connection + * is for a SOURCE or SINK node of a directed edge. + * + * From the perspective of a SOURCE node + * They have trust in the SINK node + * Their trust is based on the trustworthiness of the SINK node + * Their trust influences their interactions towards the sink along this edge and connection type, e.g., they may not even chose not to interact + * From the perspective of the SINK node + * They have trust in the SOURCE node + * Their trust is based on the trustworthiness of the SOURCE node (as somebody interacting with them) + * Their trust influences how they may react to the incoming interaction from the SOURCE node + * Therefore, if this is a SOURCE connection type + * Trust is associated with the SOURCE node + * Trustworthiness is associated with the SINK node + * And, conversely, if this is a SINK connection type + * Trust is associated with the SINK node + * Trustworthiness is associated with the SOURCE node + * @see Edge + * @see Agent + * @author Vegard Engen + */ +public class Connection implements Serializable +{ + private String connectionID; + private ConnectionType connectionType; + private double trust; + private double trustworthiness; + private Map properties; + + /** + * Default constructor, which sets an empty connection ID, the connection type as SOURCE, + * initialises the Map of properties and the trust parameters to zero. + */ + public Connection() + { + this.connectionID = ""; + this.connectionType = ConnectionType.SOURCE; + this.trust = 0; + this.trustworthiness = 0; + this.properties = new HashMap<>(); + } + + /** + * Calls the default constructor and sets the ID of the connection. + * @param id The ID/name of the connection. + */ + public Connection(String id) + { + this(); + this.connectionID = id; + } + + /** + * Calls the default constructor and sets the ID and type for the connection. + * @param id The ID/name of the connection. + * @param type The type of the connection (SOURCE or SINK). + */ + public Connection(String id, ConnectionType type) + { + this(id); + this.connectionType = type; + } + + /** + * Calls the default constructor and sets the ID and type for the connection, + * as well as the trust/trustworthiness properties. + * @param id The ID/name of the connection. + * @param type The type of the connection (SOURCE or SINK). + * @param trust The level of trust. + * @param trustworthiness The level of trustworthiness. + */ + public Connection (String id, ConnectionType type, double trust, double trustworthiness) + { + this(id, type); + this.trust = trust; + this.trustworthiness = trustworthiness; + } + + /** + * Get the ID/name of the connection. + * @return String. + */ + public String getConnectionID() + { + return connectionID; + } + + /** + * Set the ID/name of the connection. + * @param connectionID String representing the ID/name of the connection. + */ + public void setConnectionID(String connectionID) + { + this.connectionID = connectionID; + } + + /** + * Get the type of connection. + * @return ConnectionType enum. + */ + public ConnectionType getConnectionType() + { + return connectionType; + } + + /** + * Set the type of connection. + * @param connectionType Enum for the connection type. + */ + public void setConnectionType(ConnectionType connectionType) + { + this.connectionType = connectionType; + } + + /** + * Get the trust the agent has in the sink node along this connection. + * @return A float representing the level of trust. + */ + public double getTrust() + { + return trust; + } + + /** + * Set the level of trust the agent has in the sink node along this connection. + * @param trust A float representing the level of trust. + */ + public void setTrust(double trust) + { + this.trust = trust; + } + + /** + * Get the trustworthiness the agent represents to the source node along this connection. + * @return A float representing the level of trust. + */ + public double getTrustworthiness() + { + return trustworthiness; + } + + /** + * Set the level of trustworthiness the agent represents to the source node along this connection. + * @param trustworthiness A float representing the level of trust. + */ + public void setTrustworthiness(double trustworthiness) + { + this.trustworthiness = trustworthiness; + } + + /** + * Get the map of properties, in which the key represents the name of the property. + * @return A Map of numeric (floats) properties in which the key represents the name of the property. + */ + public Map getProperties() + { + return properties; + } + + /** + * Get the value of a property given the key provided as an argument to this method call. + * @param key String representing the name of a property. + * @return The numeric (float) value of a property given the provided name. + */ + public Double getProperty(String key) + { + return this.properties.get(key); + } + + /** + * Set bespoke properties for the connection. + * @param properties Map of properties and their values, in which the Key is the name of each property. + */ + public void setProperties(Map properties) + { + this.properties = properties; + } + + /** + * Set a bespoke property for the connection. + * @param key Name of the property. + * @param value Value of the property. + */ + public void setProperty(String key, Double value) + { + this.properties.put(key, value); + } +} diff --git a/src/main/java/uk/ac/soton/itinnovation/hmncore/ConnectionType.java b/src/main/java/uk/ac/soton/itinnovation/hmncore/ConnectionType.java new file mode 100644 index 0000000..a98857e --- /dev/null +++ b/src/main/java/uk/ac/soton/itinnovation/hmncore/ConnectionType.java @@ -0,0 +1,79 @@ +///////////////////////////////////////////////////////////////////////// +// +// © University of Southampton IT Innovation Centre, 2017 +// +// Copyright in this software belongs to University of Southampton +// IT Innovation Centre of Gamma House, Enterprise Road, +// Chilworth Science Park, Southampton, SO16 7NS, UK. +// +// This software may not be used, sold, licensed, transferred, copied +// or reproduced in whole or in part in any manner or form or in or +// on any media by any person other than in accordance with the terms +// of the Licence Agreement supplied with the software, or otherwise +// without the prior written consent of the copyright owners. +// +// This software is distributed WITHOUT ANY WARRANTY, without even the +// implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +// PURPOSE, except where stated in the Licence Agreement supplied with +// the software. +// +// Created By : Vegard Engen +// Created Date : 2017-02-02 +// Created for Project : HUMANE +// +///////////////////////////////////////////////////////////////////////// +package uk.ac.soton.itinnovation.hmncore; + +import java.io.Serializable; +import java.util.ArrayList; +import java.util.List; + +/** + * An enumeration representing the type of connection, whether SOURCE or SINK + * (from the perspective of a Node to an Edge). + * @author Vegard Engen + */ +public enum ConnectionType implements Serializable +{ + SOURCE("source"), SINK("sink"); + + String name; + + private ConnectionType(String type) + { + this.name = type; + } + + public String getName() + { + return name; + } + + @Override + public String toString () + { + return name; + } + + public static List getAllowedTypes() + { + List allowed = new ArrayList<> (); + allowed.add(SOURCE.name); + allowed.add(SINK.name); + return allowed; + } + + public static boolean isAllowed (String type) + { + for (ConnectionType inst : values()) + { + if (inst.name.equals(type)) + return true; + } + return false; + } + + public static ConnectionType fromValue(String v) { + return valueOf(v.toUpperCase()); + } +} diff --git a/src/main/java/uk/ac/soton/itinnovation/hmncore/CultureType.java b/src/main/java/uk/ac/soton/itinnovation/hmncore/CultureType.java new file mode 100644 index 0000000..7894dc1 --- /dev/null +++ b/src/main/java/uk/ac/soton/itinnovation/hmncore/CultureType.java @@ -0,0 +1,80 @@ +///////////////////////////////////////////////////////////////////////// +// +// © University of Southampton IT Innovation Centre, 2017 +// +// Copyright in this software belongs to University of Southampton +// IT Innovation Centre of Gamma House, Enterprise Road, +// Chilworth Science Park, Southampton, SO16 7NS, UK. +// +// This software may not be used, sold, licensed, transferred, copied +// or reproduced in whole or in part in any manner or form or in or +// on any media by any person other than in accordance with the terms +// of the Licence Agreement supplied with the software, or otherwise +// without the prior written consent of the copyright owners. +// +// This software is distributed WITHOUT ANY WARRANTY, without even the +// implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +// PURPOSE, except where stated in the Licence Agreement supplied with +// the software. +// +// Created By : Vegard Engen +// Created Date : 2017-02-09 +// Created for Project : HUMANE +// +///////////////////////////////////////////////////////////////////////// +package uk.ac.soton.itinnovation.hmncore; + +import java.io.Serializable; +import java.util.ArrayList; +import java.util.List; + +/** + * An enum representing a type of culture, distinguished here as either + * COLLECTIVE, INDIVIDUALISTIC or OTHER. + * @author Vegard Engen + */ +public enum CultureType implements Serializable +{ + COLLECTIVE("collective"), INDIVIDUALISTIC("individualistic"), OTHER("other"); + + String name; + + private CultureType(String type) + { + this.name = type; + } + + public String getName() + { + return name; + } + + @Override + public String toString () + { + return name; + } + + public static List getAllowedTypes() + { + List allowed = new ArrayList<> (); + allowed.add(COLLECTIVE.name); + allowed.add(INDIVIDUALISTIC.name); + allowed.add(OTHER.name); + return allowed; + } + + public static boolean isAllowed (String type) + { + for (CultureType inst : values()) + { + if (inst.name.equals(type)) + return true; + } + return false; + } + + public static CultureType fromValue(String v) { + return valueOf(v.toUpperCase()); + } +} diff --git a/src/main/java/uk/ac/soton/itinnovation/hmncore/Edge.java b/src/main/java/uk/ac/soton/itinnovation/hmncore/Edge.java new file mode 100644 index 0000000..ccb12d7 --- /dev/null +++ b/src/main/java/uk/ac/soton/itinnovation/hmncore/Edge.java @@ -0,0 +1,317 @@ +///////////////////////////////////////////////////////////////////////// +// +// © University of Southampton IT Innovation Centre, 2017 +// +// Copyright in this software belongs to University of Southampton +// IT Innovation Centre of Gamma House, Enterprise Road, +// Chilworth Science Park, Southampton, SO16 7NS, UK. +// +// This software may not be used, sold, licensed, transferred, copied +// or reproduced in whole or in part in any manner or form or in or +// on any media by any person other than in accordance with the terms +// of the Licence Agreement supplied with the software, or otherwise +// without the prior written consent of the copyright owners. +// +// This software is distributed WITHOUT ANY WARRANTY, without even the +// implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +// PURPOSE, except where stated in the Licence Agreement supplied with +// the software. +// +// Created By : Vegard Engen +// Created Date : 2017-02-02 +// Created for Project : HUMANE +// +///////////////////////////////////////////////////////////////////////// +package uk.ac.soton.itinnovation.hmncore; + +import java.io.Serializable; +import java.util.HashMap; +import java.util.Map; +import java.util.UUID; + +/** + * A class representing an Edge between two Nodes in the HMN, which has a start + * and an end Connection to the two respective Nodes. + * + * @see Connection + * @see Node + * @author Vegard Engen + */ +public class Edge implements Serializable +{ + private String edgeID; + private Node sourceNode; + private Node sinkNode; + private Map sourceConnections; // connections of different types (the String key) from source node encoding properties affecting how the source node may interact with the sink node + private Map sinkConnections; // connection of different types (the String key) to sink node encoding properties affecting how the destination node may react to interactions from the source node + private Map edgeConnectionStats; // key = connection type + private EdgeStats edgeStats; // assumed to aggregate stats across all connection edge stats objects + + /** + * Default constructor, initialising the properties of the Edge class. + */ + public Edge() + { + sourceConnections = new HashMap<>(); + sinkConnections = new HashMap<>(); + edgeConnectionStats = new HashMap<>(); + edgeStats = new EdgeStats(); + } + + /** + * Constructor for setting a minimum set of properties of the Edge class. + * Sets a random UUID as the edge ID. + * @param srcNode The Node at the SOURCE end of the edge. + * @param sinkNode The Node at the SINK end of the edge. + */ + public Edge(Node srcNode, Node sinkNode) + { + this(); + this.sourceNode = srcNode; + this.sinkNode = sinkNode; + this.edgeID = UUID.randomUUID().toString(); + } + + /** + * Constructor for setting key properties of the Edge class, including it's ID, + * nodes and a set of connections from each to the edge. + * Sets a random UUID as the edge ID. + * @param srcNode The Node at the SOURCE end of the edge. + * @param sinkNode The Node at the SINK end of the edge. + * @param conType A String representing the name of the type of connection to be added. + * @param srcCon Connection from the SOURCE node to the edge. + * @param sinkCon Connection from the SINK node to the edge. + */ + public Edge(Node srcNode, Node sinkNode, String conType, Connection srcCon, Connection sinkCon) + { + this(srcNode, sinkNode); + this.sourceConnections.put(conType, srcCon); + this.sinkConnections.put(conType, sinkCon); + } + + /** + * Constructor for setting a minimum set of properties of the Edge class. + * @param eID The ID of the edge. + * @param srcNode The Node at the SOURCE end of the edge. + * @param sinkNode The Node at the SINK end of the edge. + */ + public Edge(String eID, Node srcNode, Node sinkNode) + { + this(); + this.edgeID = eID; + this.sourceNode = srcNode; + this.sinkNode = sinkNode; + } + + /** + * Constructor for setting key properties of the Edge class, including it's ID, + * nodes and a set of connections from each to the edge. + * @param eID The ID of the edge. + * @param srcNode The Node at the SOURCE end of the edge. + * @param sinkNode The Node at the SINK end of the edge. + * @param conType A String representing the name of the type of connection to be added. + * @param srcCon Connection from the SOURCE node to the edge. + * @param sinkCon Connection from the SINK node to the edge. + */ + public Edge(String eID, Node srcNode, Node sinkNode, String conType, Connection srcCon, Connection sinkCon) + { + this(eID, srcNode, sinkNode); + this.sourceConnections.put(conType, srcCon); + this.sinkConnections.put(conType, sinkCon); + } + + /** + * Get the ID of the edge. + * @return A string representing the ID of the edge. + */ + public String getEdgeID() + { + return edgeID; + } + + /** + * Set the ID of the edge. + * @param edgeID A string representing the ID of the edge. + */ + public void setEdgeID(String edgeID) + { + this.edgeID = edgeID; + } + + /** + * Get the source node of the edge. + * @return Node object. + */ + public Node getSourceNode() + { + return sourceNode; + } + + /** + * Set the source node of the edge. + * @param sourceNode Node object. + */ + public void setSourceNode(Node sourceNode) + { + this.sourceNode = sourceNode; + } + + /** + * Get the sink node of the edge. + * @return Node object. + */ + public Node getSinkNode() + { + return sinkNode; + } + + /** + * Set the sink node of the edge. + * @param sinkNode Node object. + */ + public void setSinkNode(Node sinkNode) + { + this.sinkNode = sinkNode; + } + + /** + * Get all connections for the source node. + * @return Map of connections, where the Key is a string representing the connection name/ID. + */ + public Map getSourceConnections() + { + return sourceConnections; + } + + /** + * Set the connections for the source node. + * @param sourceConnections Map of connections, where the Key is a string representing the connection name/ID. + */ + public void setSourceConnections(Map sourceConnections) + { + this.sourceConnections = sourceConnections; + } + + /** + * Add connections for the source node. + * @param sourceConnections Map of connections, where the Key is a string representing the connection name/ID. + */ + public void addSourceConnections(Map sourceConnections) + { + this.sourceConnections.putAll(sourceConnections); + } + + /** + * Add a connection for the source node. + * @param conType A string representing the connection name/ID. + * @param con The connection object. + */ + public void addSourceConnection(String conType, Connection con) + { + this.sourceConnections.put(conType, con); + } + + /** + * Get all connections for the sink node. + * @return Map of connections, where the Key is a string representing the connection name/ID. + */ + public Map getSinkConnections() + { + return sinkConnections; + } + + /** + * Set the connections for the sink node. + * @param sinkConnections Map of connections, where the Key is a string representing the connection name/ID. + */ + public void setSinkConnections(Map sinkConnections) + { + this.sinkConnections = sinkConnections; + } + + /** + * Add connections for the sink node. + * @param sinkConnections Map of connections, where the Key is a string representing the connection name/ID. + */ + public void addSinkConnections(Map sinkConnections) + { + this.sinkConnections.putAll(sinkConnections); + } + + /** + * Add a connection for the sink node. + * @param conType A string representing the connection name/ID. + * @param con The connection object. + */ + public void addSinkConnection(String conType, Connection con) + { + this.sinkConnections.put(conType, con); + } + + /** + * Add a set of connections, one for each of the nodes the edge connects. + * @param connectionType A string representing the connection name/ID. + * @param srcConnection Connection object for the source node. + * @param sinkConnection Connection object for the sink node. + */ + public void addConnectionSet(String connectionType, Connection srcConnection, Connection sinkConnection) + { + this.addSourceConnection(connectionType, srcConnection); + this.addSinkConnection(connectionType, sinkConnection); + } + + /** + * Get edge stats pertaining to the specific connections. + * @return Map of edge stats, where the Key is a string representing the connection name/ID. + */ + public Map getEdgeConnectionStats() + { + return edgeConnectionStats; + } + + /** + * Sets the edge connection stats. + * @param edgeStats Map of edge stats, where the Key is a string representing the connection name/ID. + */ + public void setEdgeConnectionStats(Map edgeStats) + { + this.edgeConnectionStats = edgeStats; + } + + /** + * Add edge stats pertaining to a type of connection (the key). + * @param edgeStats Map of edge stats, where the Key is a string representing the connection name/ID. + */ + public void addEdgeConnectionStats(Map edgeStats) + { + this.edgeConnectionStats.putAll(edgeStats); + } + + /** + * Add an age stats object pertaing to a type of connection. + * @param conType A string representing the name/ID of the connection type. + * @param edgeStats An EdgeStats object. + */ + public void addEdgeConnectionStats(String conType, EdgeStats edgeStats) + { + this.edgeConnectionStats.put(conType, edgeStats); + } + + /** + * Get edge stats (assumed to be aggregated across all connections). + * @return EdgeStats object. + */ + public EdgeStats getEdgeStats() + { + return edgeStats; + } + + /** + * Sets the edge stats. + * @param edgeStats EdgeStats object. + */ + public void setEdgeStats(EdgeStats edgeStats) + { + this.edgeStats = edgeStats; + } +} diff --git a/src/main/java/uk/ac/soton/itinnovation/hmncore/EdgeStats.java b/src/main/java/uk/ac/soton/itinnovation/hmncore/EdgeStats.java new file mode 100644 index 0000000..8526113 --- /dev/null +++ b/src/main/java/uk/ac/soton/itinnovation/hmncore/EdgeStats.java @@ -0,0 +1,102 @@ +///////////////////////////////////////////////////////////////////////// +// +// © University of Southampton IT Innovation Centre, 2017 +// +// Copyright in this software belongs to University of Southampton +// IT Innovation Centre of Gamma House, Enterprise Road, +// Chilworth Science Park, Southampton, SO16 7NS, UK. +// +// This software may not be used, sold, licensed, transferred, copied +// or reproduced in whole or in part in any manner or form or in or +// on any media by any person other than in accordance with the terms +// of the Licence Agreement supplied with the software, or otherwise +// without the prior written consent of the copyright owners. +// +// This software is distributed WITHOUT ANY WARRANTY, without even the +// implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +// PURPOSE, except where stated in the Licence Agreement supplied with +// the software. +// +// Created By : Vegard Engen +// Created Date : 2017-02-03 +// Created for Project : HUMANE +// +///////////////////////////////////////////////////////////////////////// +package uk.ac.soton.itinnovation.hmncore; + +import java.io.Serializable; + +/** + * A class encapsulating statistics for an Edge, which in the Edge class may be + * distinguished on the bases of each type of Connection. + * @see Edge + * @see Connection + * @author Vegard Engen + */ +public class EdgeStats implements Serializable +{ + private int interactionStrength; + private int numInteractions; + + /** + * Default constructor initialising the variables of the object (to zero). + */ + public EdgeStats() + { + interactionStrength = 0; + numInteractions = 0; + } + + /** + * Get the interaction strength. + * @return Interaction strength value. + */ + public int getInteractionStrength() + { + return interactionStrength; + } + + /** + * Set the interaction strength. + * @param interactionStrength Interaction strength value. + */ + public void setInteractionStrength(int interactionStrength) + { + this.interactionStrength = interactionStrength; + } + + /** + * Get the number of interactions. + * @return Value for the number of interactions. + */ + public int getNumInteractions() + { + return numInteractions; + } + + /** + * Set the number of interactions. + * @param numInteractions Value for the number of interactions. + */ + public void setNumInteractions(int numInteractions) + { + this.numInteractions = numInteractions; + } + + /** + * Add an interaction (increments by 1). + */ + public void addInteraction() + { + this.numInteractions++; + } + + /** + * Add interactions by some variable amount. + * @param i The number of interactions to add. + */ + public void addInteractions(int i) + { + this.numInteractions = this.numInteractions + i; + } +} diff --git a/src/main/java/uk/ac/soton/itinnovation/hmncore/GenderType.java b/src/main/java/uk/ac/soton/itinnovation/hmncore/GenderType.java new file mode 100644 index 0000000..19729cd --- /dev/null +++ b/src/main/java/uk/ac/soton/itinnovation/hmncore/GenderType.java @@ -0,0 +1,84 @@ +///////////////////////////////////////////////////////////////////////// +// +// © University of Southampton IT Innovation Centre, 2017 +// +// Copyright in this software belongs to University of Southampton +// IT Innovation Centre of Gamma House, Enterprise Road, +// Chilworth Science Park, Southampton, SO16 7NS, UK. +// +// This software may not be used, sold, licensed, transferred, copied +// or reproduced in whole or in part in any manner or form or in or +// on any media by any person other than in accordance with the terms +// of the Licence Agreement supplied with the software, or otherwise +// without the prior written consent of the copyright owners. +// +// This software is distributed WITHOUT ANY WARRANTY, without even the +// implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +// PURPOSE, except where stated in the Licence Agreement supplied with +// the software. +// +// Created By : Vegard Engen +// Created Date : 2017-02-02 +// Created for Project : HUMANE +// +///////////////////////////////////////////////////////////////////////// +package uk.ac.soton.itinnovation.hmncore; + +import java.io.Serializable; +import java.util.ArrayList; +import java.util.List; + +/** + * An enumeration representing the gender of a Human agent (node), only including + * a subset of genders with an 'other' option. + * Supported genders are: FEMALE, MALE, AGENDER, ANDOGYNE and OTHER. + * @author Vegard Engen + */ +public enum GenderType implements Serializable +{ + FEMALE("female"), MALE("male"), AGENDER("agender"), ANDOGYNE("androgyne"), OTHER("other"); + + String name; + + private GenderType(String type) + { + this.name = type; + } + + public String getName() + { + return name; + } + + @Override + public String toString () + { + return name; + } + + public static List getAllowedTypes() + { + List allowed = new ArrayList<> (); + allowed.add(FEMALE.name); + allowed.add(MALE.name); + allowed.add(AGENDER.name); + allowed.add(ANDOGYNE.name); + allowed.add(OTHER.name); + return allowed; + } + + public static boolean isAllowed (String type) + { + for (GenderType inst : values()) + { + if (inst.name.equals(type)) + return true; + } + return false; + } + + public static GenderType fromValue(String v) { + return valueOf(v.toUpperCase()); + } + +} diff --git a/src/main/java/uk/ac/soton/itinnovation/hmncore/HMN.java b/src/main/java/uk/ac/soton/itinnovation/hmncore/HMN.java new file mode 100644 index 0000000..beba381 --- /dev/null +++ b/src/main/java/uk/ac/soton/itinnovation/hmncore/HMN.java @@ -0,0 +1,345 @@ +///////////////////////////////////////////////////////////////////////// +// +// © University of Southampton IT Innovation Centre, 2017 +// +// Copyright in this software belongs to University of Southampton +// IT Innovation Centre of Gamma House, Enterprise Road, +// Chilworth Science Park, Southampton, SO16 7NS, UK. +// +// This software may not be used, sold, licensed, transferred, copied +// or reproduced in whole or in part in any manner or form or in or +// on any media by any person other than in accordance with the terms +// of the Licence Agreement supplied with the software, or otherwise +// without the prior written consent of the copyright owners. +// +// This software is distributed WITHOUT ANY WARRANTY, without even the +// implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +// PURPOSE, except where stated in the Licence Agreement supplied with +// the software. +// +// Created By : Vegard Engen +// Created Date : 2017-02-02 +// Created for Project : HUMANE +// +///////////////////////////////////////////////////////////////////////// +package uk.ac.soton.itinnovation.hmncore; + +import java.io.Serializable; +import java.util.ArrayList; +import java.util.GregorianCalendar; +import java.util.List; + +/** + * A class representing a Human-Machine Network (HMN), comprising Nodes and + * Edges. Nodes can be either agents or artefacts. The latter having no agency. + * + * @see Node + * @see Agent + * @see Artefact + * @see Edge + * + * @author Vegard Engen + */ +public class HMN implements Serializable +{ + // may benefit from changing the Node usage here to Agent and Artefact, respectively + protected String name; + protected List agents; + protected List artefacts; + protected List edges; + private GregorianCalendar currentDateTime; + + /** + * Default constructor, initialising empty node and edge lists. + */ + public HMN() + { + agents = new ArrayList<>(); + artefacts = new ArrayList<>(); + edges = new ArrayList<>(); + } + + /** + * Constructor setting the name of the HMN. + * @param name Name of the HMN. + */ + public HMN(String name) + { + this(); + this.name = name; + } + + /** + * Constructor to initialise the node and edge lists with the lists provided + * as arguments. + * + * @param agents List of Agents representing agents (humans or machines). + * @param artefacts List of Artefacts representing artefacts. + * @param edges List of Edges. + */ + public HMN(List agents, List artefacts, List edges) + { + this(); + if (agents != null) { + this.agents.addAll(agents); + } + if (artefacts != null) { + this.artefacts.addAll(artefacts); + } + if (edges != null) { + this.edges.addAll(edges); + } + } + + /** + * Get the name of HMN. + * @return The name of the HMN. + */ + public String getName() + { + return name; + } + + /** + * Set the name of the HMN. + * @param name A string of the name of the HMN. + */ + public void setName(String name) + { + this.name = name; + } + + /** + * Removes an agent from the HMN, given the ID provided. + * @param id The ID of the agent to be removed. + * @return Returns if the node was found and removed successfully; False if not found, or not removed successfully. + */ + public boolean removeAgent(String id) + { + for (Node n : agents) { + if (n.getNodeID().equals(id)) { + return agents.remove(n); + } + } + return false; + } + + /** + * Removes an agent from the HMN, given the Node object provided. + * @param n Node object to be removed. + * @return Returns true if the HMN contained the node and it was removed successfully; false otherwise. + * @throws NullPointerException If n is NULL. + */ + public boolean removeAgent(Node n) throws NullPointerException + { + if (n == null) { + throw new NullPointerException("Cannot remove the node from the HMN as the object provided was NULL"); + } + + return agents.remove(n); + } + + /** + * Removes an artefact from the HMN, given the ID provided. + * @param id The ID of the artefact to be removed. + * @return Returns true if the node was found and removed successfully; False if not found, or not removed successfully. + */ + public boolean removeArtefact(String id) + { + for (Node n : artefacts) { + if (n.getNodeID().equals(id)) { + return artefacts.remove(n); + } + } + return false; + } + + /** + * Removes an artefact from the HMN, given the Node object provided. + * @param n Node object to be removed. + * @return Returns true if the HMN contained the node and it was removed successfully; false otherwise. + * @throws NullPointerException If n is NULL. + */ + public boolean removeArtefact(Node n) throws NullPointerException + { + if (n == null) { + throw new NullPointerException("Cannot remove the node from the HMN as the object provided was NULL"); + } + + return artefacts.remove(n); + } + + /** + * Removes an edge from the HMN, given the ID provided. + * @param id ID of the edge to be removed. + * @return Returns true if the HMN contained the edge and it was removed successfully; false otherwise. + */ + public boolean removeEdge(String id) + { + for (Edge e : edges) { + if (e.getEdgeID().equals(id)) { + return edges.remove(e); + } + } + return false; + } + + /** + * Removes an edge from the HMN, given the Edge object provided. + * @param e Edge object to be removed. + * @return Returns true if the HMN contained the edge and it was removed successfully; false otherwise. + * @throws NullPointerException If e is NULL. + */ + public boolean removeEdge(Edge e) throws NullPointerException + { + if (e == null) { + throw new NullPointerException("Cannot remove the edge from the HMN as the object provided was NULL"); + } + + return edges.remove(e); + } + + /** + * Get all Agent nodes in the HMN. + * @return List of Agent objects. + */ + public List getAgents() + { + return agents; + } + + /** + * Set all Agent nodes in the HMN according to the provided list. + * This will replace the existing list without calling any clean-up methods. + * Consider using the add-methods if this is not desirable. + * @param agents List of Agents + */ + public void setAgents(List agents) + { + // this.nodes.clear(); // Left this here in case there would be an advantage to clear the list first + this.agents = agents; + } + + /** + * Get all Artefact nodes in the HMN. + * @return List of Artefact objects. + */ + public List getArtefacts() + { + return artefacts; + } + + /** + * Set all Artefact nodes in the HMN according to the provided list. + * This will replace the existing list without calling any clean-up methods. + * Consider using the add-methods if this is not desirable. + * @param artefacts List of Artefact nodes + */ + public void setArtefacts(List artefacts) + { + // this.nodes.clear(); // Left this here in case there would be an advantage to clear the list first + this.artefacts = artefacts; + } + + /** + * Add Agent nodes to the HMN. + * @param agents List of Agents to be added to the agent list. + */ + public void addAgents(List agents) + { + this.agents.addAll(agents); + } + + /** + * Add an Agent node to the HMN. + * @param node An Agent object to add to the agent list of Nodes. + */ + public void addAgent(Agent node) + { + this.agents.add(node); + } + + /** + * Add Artefact nodes to the HMN. + * @param artefacts List of Artefact nodes. + */ + public void addArtefacts(List artefacts) + { + this.artefacts.addAll(artefacts); + } + + /** + * Add an Artefact node to the HMN. + * @param node An Artefact object to add to the list of artefacts. + */ + public void addArtefact(Artefact node) + { + this.artefacts.add(node); + } + + /** + * Get all the edges in the HMN. + * @return List of edges. + */ + public List getEdges() + { + return edges; + } + + /** + * Set the edges of the HMN according to the list provided. + * This will replace the existing list without calling any clean-up methods. + * Consider using the addEdge(..) methods if this is not desirable. + * @param edges List of Edge objects. + */ + public void setEdges(List edges) + { + this.edges = edges; + } + + /** + * Add edges to the HMN according to the list provided. + * @param edges List of Edge objects. + */ + public void addEdges(List edges) + { + this.edges.addAll(edges); + } + + /** + * Add an edge to the HMN according to the object provided. + * @param edge Edge object to add to the HMN. + */ + public void addEdge(Edge edge) + { + this.edges.add(edge); + } + + /** + * Get the current simulation date and time, which a simulation may use (if synchronised) + * to set properties such as creation and edit dates for content in an HMN. + * @return GregorianCalendar instance of the current simulation date/time. + */ + public GregorianCalendar getCurrentDateTime() + { + return currentDateTime; + } + + /** + * Set the current simulation date and time. + * @param currentDateTime GregorianCalendar instance. + */ + public void setCurrentDateTime(GregorianCalendar currentDateTime) + { + this.currentDateTime = currentDateTime; + } + + /** + * Increment the current simulation date/time. + * @param seconds The increment in seconds. + */ + public void incrementCurrentDateTime(int seconds) + { + this.currentDateTime.add(GregorianCalendar.SECOND, seconds); + } +} diff --git a/src/main/java/uk/ac/soton/itinnovation/hmncore/Human.java b/src/main/java/uk/ac/soton/itinnovation/hmncore/Human.java new file mode 100644 index 0000000..2f1e3e5 --- /dev/null +++ b/src/main/java/uk/ac/soton/itinnovation/hmncore/Human.java @@ -0,0 +1,206 @@ +///////////////////////////////////////////////////////////////////////// +// +// © University of Southampton IT Innovation Centre, 2017 +// +// Copyright in this software belongs to University of Southampton +// IT Innovation Centre of Gamma House, Enterprise Road, +// Chilworth Science Park, Southampton, SO16 7NS, UK. +// +// This software may not be used, sold, licensed, transferred, copied +// or reproduced in whole or in part in any manner or form or in or +// on any media by any person other than in accordance with the terms +// of the Licence Agreement supplied with the software, or otherwise +// without the prior written consent of the copyright owners. +// +// This software is distributed WITHOUT ANY WARRANTY, without even the +// implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +// PURPOSE, except where stated in the Licence Agreement supplied with +// the software. +// +// Created By : Vegard Engen +// Created Date : 2017-02-02 +// Created for Project : HUMANE +// +///////////////////////////////////////////////////////////////////////// +package uk.ac.soton.itinnovation.hmncore; + +import java.io.Serializable; + +/** + * An abstract class representing a Human in the HMN and their core properties. + * @author Vegard Engen + */ +public abstract class Human extends Agent implements Serializable +{ + protected int age; + protected GenderType gender; + protected SexualOrientationType sexualOrientation; + protected CultureType culture; // collective vs individualistic + protected double selfEfficacy; + protected double computerSelfEfficacy; + protected double trust; + protected int reputation; + + /** + * Default constructor, initialises all the properties of the class. + */ + public Human() + { + this.age = 0; + this.gender = GenderType.OTHER; + this.sexualOrientation = SexualOrientationType.OTHER; + this.culture = CultureType.OTHER; + this.selfEfficacy = 0; + this.computerSelfEfficacy = 0; + this.trust = 0; + this.reputation = 0; + } + + /** + * Get the age of the human agent. + * @return Integer representing the age in years. + */ + public int getAge() + { + return age; + } + + /** + * Set the age of the human agent. + * @param age Integer representing the age in years. + */ + public void setAge(int age) + { + this.age = age; + } + + /** + * Get the gender of the human agent. + * @return GenderType enum. + */ + public GenderType getGender() + { + return gender; + } + + /** + * Set the gender of the human agent. + * @param gender GenderType enum. + */ + public void setGender(GenderType gender) + { + this.gender = gender; + } + + /** + * Get the sexual orientation of the human agent. + * @return SexualOrientationType enum. + */ + public SexualOrientationType getSexualOrientation() + { + return sexualOrientation; + } + + /** + * Set the sexual orientation of the human agent. + * @param sexualOrientation SexualOrientationType enum. + */ + public void setSexualOrientation(SexualOrientationType sexualOrientation) + { + this.sexualOrientation = sexualOrientation; + } + + /** + * Get the reputation of the human agent. + * @return Integer representing a reputation value for the agent. + */ + public int getReputation() + { + return reputation; + } + + /** + * Set the reputation of the human agent. + * @param reputation Integer representing a reputation value for the agent. + */ + public void setReputation(int reputation) + { + this.reputation = reputation; + } + + /** + * Get the general (propensity to) trust value for the human agent. + * @return Float representing a trust value for the agent. + */ + public double getTrust() + { + return trust; + } + + /** + * Set the general (propensity to) trust value for the human agent. + * @param trust Float representing a trust value for the agent. + */ + public void setTrust(double trust) + { + this.trust = trust; + } + + /** + * Get the culture type of the HUMAN agent. + * @return CultureType enum. + */ + public CultureType getCulture() + { + return culture; + } + + /** + * Set the culture type of the HUMAN agent. + * @param culture CultureType enum. + */ + public void setCulture(CultureType culture) + { + this.culture = culture; + } + + /** + * Get the self-efficacy of the human agent. That is, the belief that they + * are able to achieve their goals. + * @return A float representing a self-efficacy value for the agent. + */ + public double getSelfEfficacy() + { + return selfEfficacy; + } + + /** + * Set the self-efficacy of the human agent.That is, the belief that they + * are able to achieve their goals. + * @param selfEfficacy A float representing a self-efficacy value for the agent. + */ + public void setSelfEfficacy(double selfEfficacy) + { + this.selfEfficacy = selfEfficacy; + } + + /** + * Get the computer-mediated self-efficacy of the human agent. That is, the belief that they + * are able to achieve their goals using the machines in the HMN. + * @return A float representing a computer-mediated self-efficacy value for the agent. + */ + public double getComputerSelfEfficacy() + { + return computerSelfEfficacy; + } + + /** + * Get the computer-mediated self-efficacy of the human agent. That is, the belief that they + * are able to achieve their goals using the machines in the HMN. + * @param computerSelfEfficacy A float representing a computer-mediated self-efficacy value for the agent. + */ + public void setComputerSelfEfficacy(double computerSelfEfficacy) + { + this.computerSelfEfficacy = computerSelfEfficacy; + } +} diff --git a/src/main/java/uk/ac/soton/itinnovation/hmncore/Machine.java b/src/main/java/uk/ac/soton/itinnovation/hmncore/Machine.java new file mode 100644 index 0000000..8092ae0 --- /dev/null +++ b/src/main/java/uk/ac/soton/itinnovation/hmncore/Machine.java @@ -0,0 +1,164 @@ +///////////////////////////////////////////////////////////////////////// +// +// © University of Southampton IT Innovation Centre, 2017 +// +// Copyright in this software belongs to University of Southampton +// IT Innovation Centre of Gamma House, Enterprise Road, +// Chilworth Science Park, Southampton, SO16 7NS, UK. +// +// This software may not be used, sold, licensed, transferred, copied +// or reproduced in whole or in part in any manner or form or in or +// on any media by any person other than in accordance with the terms +// of the Licence Agreement supplied with the software, or otherwise +// without the prior written consent of the copyright owners. +// +// This software is distributed WITHOUT ANY WARRANTY, without even the +// implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +// PURPOSE, except where stated in the Licence Agreement supplied with +// the software. +// +// Created By : Vegard Engen +// Created Date : 2017-02-02 +// Created for Project : HUMANE +// +///////////////////////////////////////////////////////////////////////// +package uk.ac.soton.itinnovation.hmncore; + +import java.io.Serializable; + +/** + * An abstract class representing a Machine in the HMN and its core properties. + * @author Vegard Engen + */ +public abstract class Machine extends Agent implements Serializable +{ + protected double capacity; + protected double availability; + protected double reliability; + protected double responsiveness; + protected double throughput; + protected double utilisation; + + /** + * Default constructor, initialising all the properties of the class. + */ + public Machine() + { + this.capacity = 0; + this.availability = 0; + this.reliability = 0; + this.responsiveness = 0; + this.throughput = 0; + this.utilisation = 0; + } + + /** + * Get the capacity of the machine agent. + * @return A float representing the capacity of the machine agent. + */ + public double getCapacity() + { + return capacity; + } + + /** + * Get the capacity of the machine agent. + * @param capacity A float representing the capacity of the machine agent. + */ + public void setCapacity(double capacity) + { + this.capacity = capacity; + } + + /** + * Get the availability of the machine agent. + * @return A float representing the availability of the machine agent. + */ + public double getAvailability() + { + return availability; + } + + /** + * Set the availability of the machine agent. + * @param availability A float representing the availability of the machine agent. + */ + public void setAvailability(double availability) + { + this.availability = availability; + } + + /** + * Get the reliability of the machine agent. + * @return A float representing the reliability of the machine agent. + */ + public double getReliability() + { + return reliability; + } + + /** + * Set the reliability of the machine agent. + * @param reliability A float representing the reliability of the machine agent. + */ + public void setReliability(double reliability) + { + this.reliability = reliability; + } + + /** + * Get the responsiveness of the machine agent. + * @return A float representing the responsiveness of the machine agent. + */ + public double getResponsiveness() + { + return responsiveness; + } + + /** + * Set the responsiveness of the machine agent. + * @param responsiveness A float representing the responsiveness of the machine agent. + */ + public void setResponsiveness(double responsiveness) + { + this.responsiveness = responsiveness; + } + + /** + * Get the throughput of the machine agent. + * @return A float representing the throughput of the machine agent. + */ + public double getThroughput() + { + return throughput; + } + + /** + * Set the throughput of the machine agent. + * @param throughput A float representing the throughput of the machine agent. + */ + public void setThroughput(double throughput) + { + this.throughput = throughput; + } + + /** + * Get the utilisation of the machine agent. + * @return A float representing the utilisation of the machine agent. + */ + public double getUtilisation() + { + return utilisation; + } + + /** + * Set the utilisation of the machine agent. + * @param utilisation A float representing the utilisation of the machine agent. + */ + public void setUtilisation(double utilisation) + { + this.utilisation = utilisation; + } + + +} diff --git a/src/main/java/uk/ac/soton/itinnovation/hmncore/Node.java b/src/main/java/uk/ac/soton/itinnovation/hmncore/Node.java new file mode 100644 index 0000000..03c39ae --- /dev/null +++ b/src/main/java/uk/ac/soton/itinnovation/hmncore/Node.java @@ -0,0 +1,368 @@ +///////////////////////////////////////////////////////////////////////// +// +// © University of Southampton IT Innovation Centre, 2017 +// +// Copyright in this software belongs to University of Southampton +// IT Innovation Centre of Gamma House, Enterprise Road, +// Chilworth Science Park, Southampton, SO16 7NS, UK. +// +// This software may not be used, sold, licensed, transferred, copied +// or reproduced in whole or in part in any manner or form or in or +// on any media by any person other than in accordance with the terms +// of the Licence Agreement supplied with the software, or otherwise +// without the prior written consent of the copyright owners. +// +// This software is distributed WITHOUT ANY WARRANTY, without even the +// implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +// PURPOSE, except where stated in the Licence Agreement supplied with +// the software. +// +// Created By : Vegard Engen +// Created Date : 2017-02-02 +// Created for Project : HUMANE +// +///////////////////////////////////////////////////////////////////////// +package uk.ac.soton.itinnovation.hmncore; + +import java.io.Serializable; +import java.util.ArrayList; +import java.util.List; + +/** + * A class that represents a node in a HMN. + * + * @author Vegard Engen + */ +public class Node implements Serializable +{ + protected String nodeID; + protected List inboundEdges; + protected List outboundEdges; + + // This HMN object is needed for remove methods, to help synchronise with the "master" list in + // the HMN object. Also agents may need access to (all) artefacts and other agents, + // which we can provide via this HMN object. + protected HMN hmn; + + /** + * Default constructor, initialising empty connection lists. + */ + public Node() + { + nodeID = ""; + inboundEdges = new ArrayList<>(); + outboundEdges = new ArrayList<>(); + } + + /** + * Calls the default constructor and sets the ID of the node. + * @param nodeID The ID of the node. + */ + public Node(String nodeID) + { + this.nodeID = nodeID; + } + + /** + * Calls the default constructor, sets the ID of the node and initialises the + * connection lists with the lists provided as arguments. + * + * @param nodeID The ID of the node. + * @param inboundEdges List of inbound edges. + * @param outboundEdges List of outbound edges. + */ + public Node(String nodeID, List inboundEdges, List outboundEdges) + { + this(nodeID); + + if (inboundEdges != null) { + this.inboundEdges.addAll(inboundEdges); + } + + if (outboundEdges != null) { + this.outboundEdges.addAll(outboundEdges); + } + } + + /** + * Constructor to set a reference to the HMN. + * @param hmn Human-machine network object (reference). + */ + public Node(HMN hmn) + { + this.hmn = hmn; + } + + /** + * Calls the default constructor and sets the ID of the node. + * @param hmn Human-machine network object (reference). + * @param nodeID The ID of the node. + */ + public Node(HMN hmn, String nodeID) + { + this(hmn); + this.nodeID = nodeID; + } + + /** + * Calls the default constructor, sets the ID of the node and initialises the + * connection lists with the lists provided as arguments. + * + * @param hmn Human-machine network object (reference). + * @param nodeID The ID of the node. + * @param inboundEdges List of inbound edges. + * @param outboundEdges List of outbound edges. + */ + public Node(HMN hmn, String nodeID, List inboundEdges, List outboundEdges) + { + this(hmn, nodeID); + + if (inboundEdges != null) { + this.inboundEdges.addAll(inboundEdges); + } + + if (outboundEdges != null) { + this.outboundEdges.addAll(outboundEdges); + } + } + + /** + * Get the ID of the node. + * @return String representing the ID of the node. + */ + public String getNodeID() + { + return nodeID; + } + + /** + * Sets the ID of the node. + * @param nodeID String representing the ID of the node. + */ + public void setNodeID(String nodeID) + { + this.nodeID = nodeID; + } + + /** + * Get all the inbound edges to the node. + * @return List of Edge objects. + */ + public List getInboundEdges() + { + return inboundEdges; + } + + /** + * Set all the inbound edges to the node. + * @param inboundEdges List of Edge objects. + */ + public void setInboundEdges(List inboundEdges) + { + this.inboundEdges = inboundEdges; + } + + /** + * Create an inbound edge. + * @param id ID of the edge. + * @param sinkNode The node from which the directional edge stems from. + * @param addToHMN Flag to say if the edge should also be added to the HMN's "master" list of edges. + * @return An Edge object. + */ + public Edge createInboundEdge(String id, Node sinkNode, boolean addToHMN) + { + Edge e = new Edge(); + + e.setEdgeID(nodeID); + e.setSourceNode(sinkNode); + e.setSinkNode(this); + + if (addToHMN) { + hmn.addEdge(e); + } + + return e; + } + + /** + * Create an inbound edge. + * @param id ID of the edge. + * @param srcNode The node from which the directional edge stems from. + * @param connectionType The type of connection. + * @param srcConnection The connection from the source node (the other node) to the edge. + * @param sinkConnection The connection from the sink node (this node) to this edge. + * @param addToHMN Flag to say if the edge should also be added to the HMN's "master" list of edges. + * @return An Edge object. + */ + public Edge createInboundEdge(String id, Node srcNode, String connectionType, Connection srcConnection, Connection sinkConnection, boolean addToHMN) + { + Edge e = new Edge(); + + e.setEdgeID(nodeID); + e.setSourceNode(srcNode); + e.setSinkNode(this); + e.addConnectionSet(connectionType, srcConnection, sinkConnection); + + if (addToHMN) { + hmn.addEdge(e); + } + + return e; + } + + /** + * Add an inbound edge. + * @param edge Edge object + */ + public void addInboundEdge(Edge edge) + { + this.inboundEdges.add(edge); + } + + /** + * Add a list of inbound edges. + * @param inboundEdges List of Edge objects + */ + public void addInboundEdges(List inboundEdges) + { + this.inboundEdges.addAll(inboundEdges); + } + + /** + * Removes an inbound edge, if it exists. + * @param edge Edge object to be removed. + * @param removeFromHMN A flag to signifify if the edge should be removed from the HMN's "master" list. + * @throws NullPointerException If the Edge object is NULL. + * @return True if the edge was successfully removed; false otherwise. + */ + public boolean removeInboundEdge(Edge edge, boolean removeFromHMN) throws NullPointerException + { + if (edge == null) { + throw new NullPointerException("Cannot remove the inbound edge from the Node as the object provided was NULL"); + } + + if (inboundEdges.remove(edge)) { + if (removeFromHMN) { + return hmn.removeEdge(edge); + } else { + return true; + } + } else { + return false; + } + } + + /** + * Get all outbound edges. + * @return List of Edge objects. + */ + public List getOutboundEdges() + { + return outboundEdges; + } + + /** + * Set all outbound edges. + * @param outboundEdges List of Edge objects. + */ + public void setOutboundEdges(List outboundEdges) + { + this.outboundEdges = outboundEdges; + } + + /** + * Create an outbound edge. + * @param id ID of the edge. + * @param sinkNode The the sink (other) node, at the end of this directed edge. + * @param addToHMN Flag to say if the edge should also be added to the HMN's "master" list of edges. + * @return An Edge object + */ + public Edge createOutboundEdge(String id, Node sinkNode, boolean addToHMN) + { + Edge e = new Edge(); + + e.setEdgeID(nodeID); + e.setSourceNode(this); + e.setSinkNode(sinkNode); + + if (addToHMN) { + hmn.addEdge(e); + } + + return e; + } + + /** + * Create an outbound edge. + * @param id ID of the edge. + * @param sinkNode The node to which the directional edge goes to. + * @param connectionType The type of connection. + * @param srcConnection The connection from the source node (this node) to the edge. + * @param sinkConnection The connection from the sink node (the other node) to this edge. + * @param addToHMN Flag to say if the edge should also be added to the HMN's "master" list of edges. + * @return An Edge object. + */ + public Edge createOutboundEdge(String id, Node sinkNode, String connectionType, Connection srcConnection, Connection sinkConnection, boolean addToHMN) + { + Edge e = new Edge(); + + e.setEdgeID(nodeID); + e.setSourceNode(this); + e.setSinkNode(sinkNode); + e.addConnectionSet(connectionType, srcConnection, sinkConnection); + + if (addToHMN) { + hmn.addEdge(e); + } + + return e; + } + + /** + * Add an outbound edge. + * @param edge Edge object. + */ + public void addOutboundEdge(Edge edge) + { + this.outboundEdges.add(edge); + } + + /** + * Add a list of outbound edges. + * @param outboundEdges List of Edge objects. + */ + public void addOutboundEdges(List outboundEdges) + { + this.outboundEdges.addAll(outboundEdges); + } + + /** + * Removes an outbound edge, if it exists. + * @param edge Edge object to be removed. + * @param removeFromHMN A flag to signifify if the edge should be removed from the HMN's "master" list. + * @throws NullPointerException If the Edge object is NULL. + * @return True if the edge was successfully removed; false otherwise. + */ + public boolean removeOutboundEdge(Edge edge, boolean removeFromHMN) throws NullPointerException + { + if (edge == null) { + throw new NullPointerException("Cannot remove the outbound edge from the Node as the object provided was NULL"); + } + + if (outboundEdges.remove(edge)) { + if (removeFromHMN) { + return hmn.removeEdge(edge); + } else { + return true; + } + } else { + return false; + } + } + + @Override + public String toString() + { + return this.nodeID; + } +} diff --git a/src/main/java/uk/ac/soton/itinnovation/hmncore/SexualOrientationType.java b/src/main/java/uk/ac/soton/itinnovation/hmncore/SexualOrientationType.java new file mode 100644 index 0000000..dca04c5 --- /dev/null +++ b/src/main/java/uk/ac/soton/itinnovation/hmncore/SexualOrientationType.java @@ -0,0 +1,84 @@ +///////////////////////////////////////////////////////////////////////// +// +// © University of Southampton IT Innovation Centre, 2017 +// +// Copyright in this software belongs to University of Southampton +// IT Innovation Centre of Gamma House, Enterprise Road, +// Chilworth Science Park, Southampton, SO16 7NS, UK. +// +// This software may not be used, sold, licensed, transferred, copied +// or reproduced in whole or in part in any manner or form or in or +// on any media by any person other than in accordance with the terms +// of the Licence Agreement supplied with the software, or otherwise +// without the prior written consent of the copyright owners. +// +// This software is distributed WITHOUT ANY WARRANTY, without even the +// implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +// PURPOSE, except where stated in the Licence Agreement supplied with +// the software. +// +// Created By : Vegard Engen +// Created Date : 2017-02-09 +// Created for Project : HUMANE +// +///////////////////////////////////////////////////////////////////////// +package uk.ac.soton.itinnovation.hmncore; + +import java.io.Serializable; +import java.util.ArrayList; +import java.util.List; + +/** + * An enum representing a subset of sexual orientation of human nodes, with an + * 'other' option for orientations not included here. + * Supported values are: HETEROSEXUAL, BISEXUAL, GAY, LESBIAN, ASEXUAL and OTHER. + * @author Vegard Engen + */ +public enum SexualOrientationType implements Serializable +{ + HETEROSEXUAL("heterosexual"), BISEXUAL("bisexual"), GAY("gay"), LESBIAN("lesbian"), ASEXUAL("asexual"), OTHER("other"); + + String name; + + private SexualOrientationType(String type) + { + this.name = type; + } + + public String getName() + { + return name; + } + + @Override + public String toString () + { + return name; + } + + public static List getAllowedTypes() + { + List allowed = new ArrayList<> (); + allowed.add(HETEROSEXUAL.name); + allowed.add(BISEXUAL.name); + allowed.add(GAY.name); + allowed.add(LESBIAN.name); + allowed.add(ASEXUAL.name); + allowed.add(OTHER.name); + return allowed; + } + + public static boolean isAllowed (String type) + { + for (SexualOrientationType inst : values()) + { + if (inst.name.equals(type)) + return true; + } + return false; + } + + public static SexualOrientationType fromValue(String v) { + return valueOf(v.toUpperCase()); + } +} diff --git a/src/main/resources/logback-hmncore.xml b/src/main/resources/logback-hmncore.xml new file mode 100644 index 0000000..7475567 --- /dev/null +++ b/src/main/resources/logback-hmncore.xml @@ -0,0 +1,16 @@ + + + + + + %d{HH:mm:ss.SSS} [%-5level] %logger{0}:%line - %msg%n + + + + + + + + + + \ No newline at end of file diff --git a/uml/hmn-core-uml.vsdx b/uml/hmn-core-uml.vsdx new file mode 100644 index 0000000000000000000000000000000000000000..dd77ca6b695fa9b0ed0f04f5643c94d82af14500 GIT binary patch literal 121129 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

@{Io%U- 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%0D8f)|Z0o+^*Gp#9;tE&mD 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 O9G%Y